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Disclaimer 


No  warranties  3 express  or  implied 3 are  made 
by  the  distributors  or  developers  that 
STARPAC  or  its  constituent  parts  are  free  of 
error.  They  should  not  be  relied  upon  as 
the  sole  basis  for  solving  a problem  whose 
incorrect  solution  could  result  in  injury  to 
person  or  property . If  the  programs  are 
employed  in  such  a manner3  it  is  at  the 
user's  own  risk  and  the  distributors  and 
developers  disclaim  all  liability  for  such 
misuse . 

Computers  have  been  identified  in  this  paper 
in  order  to  adequately  specify  the  sample 
programs  and  test  results.  Such 
identification  does  not  imply  recommendation 
or  endorsement  by  the  National  Bureau  of 
Standards  3 nor  does  it  imply  that  the 
equipment  identified  is  necessarily  the  best 
available  for  the  purpose. 


Preface 


STARPAC,  the  Standards  Time  Series  arid  Regression  Package,  is  a library 
of  Fortran  subroutines  for  statistical  data  analysis  developed  by  the 
Statistical  Engineering  Division  (SED)  of  the  National  Bureau  of  Standards 
(NBS),  Boulder,  Colorado.  Earlier  versions  of  this  library  were  distributed 
by  the  SED  under  the  name  STATLIB  [Tryon  and  Donaldson,  1978]  . Chapter  1 and 
chapter  9 of  this  document  were  previously  distributed  as  NBS  Technical  Notes 
1068-1  and  1068-2,  respectively  [Donaldson  and  Tryon,  1983a  and  1983b]. 
STARPAC  incorporates  many  changes  to  STATLIB,  including  additional  statistical 
techniques,  improved  algorithms  and  enhanced  portability. 

STARPAC  consists  of  families  of  subroutines  for  nonlinear  least  squares 
regression,  time  series  analysis  (in  both  time  and  frequency  domains) , line 
printer  graphics,  basic  statistical  analysis,  and  linear  least  squares 
regression.  These  subroutines  feature: 

o ease  of  use,  alone  and  with  other  Fortran  subroutine  libraries; 

© extensive  error  handling  facilities; 

® comprehensive  printed  reports; 

© no  problem  size  restrictions  other  than  effective  machine  size;  and 
• portability. 

Notation,  format  and  naming  conventions  are  constant  throughout  the 
STARPAC  documentation,  allowing  the  documentation  for  each  family  of 
subroutines  to  be  used  alone  or  in  conjunction  with  the  documentation  for 
another. 


The  code  for  STARPAC  was  developed  at  the  U.S.  Department  of  Commerce 
Boulder  Laboratories  on  a CDC  CYBER  180/840  under  NOS  2.3.  All  examples 
presented  in  this  documentation  were  executed  in  this  environment  using  the 
FTN  5.1+617  compiler  with  rounding. 

STARPAC  is  written  in  ANSI  Fortran  '77  [American  National  Standards 
Institute,  1977]  using  the  Hollerith  Extension.  Workspace  and 
machine-dependent  constants  are  supplied  using  subroutines  based  on  the  Bell 
Laboratories  "Framework  for  a Portable  Library"  [Fox  et  al.  1978a]  . We  have 
also  used  subroutines  from  LINPACK  [Dongarra  et  al.  1979]  , from  the  "Basic 
Linear  Algebra  Subprograms  for  Fortran  Usage”  [Lawson  et  al.  1979],  from 
DATAPAC  [Filliben,  1977]  and  from  the  portable  special  function  subroutines  of 
Fullerton  [1977].  The  analyses  generated  by  several  of  the  subroutine 
families  have  been  adapted  from  OMNITAB  II  [Hogben  et  al.  1971];  users  are 
directed  to  Peavy  et  al.  [1985]  for  information  about  OMNITAB  80,  the  current 
version  of  OMNITAB. 

Computer  facilities  for  the  STARPAC  project  have  been  provided  in  part  by 
the  National  Oceanic  and  Atmospheric  Administration  Mountain  Administrative 
Support  Center  Computer  Division,  Boulder,  Colorado,  and  we  gratefully 
acknowledge  their  support.  The  STARPAC  subroutine  library  is  the  result  of 


v 


the  programming  efforts  of  Janet  R.  Donaldson  and  John  E.  Koontz,  with 
assistance  from  Ginger  A.  Caldwell,  Steven  M.  Keefer,  and  Linda  L.  Mitchell. 
Valuable  contributions  have  also  been  made  by  each  of  the  members  of  the 
Statistical  Engineering  Division  in  Boulder,  and  from  many  within  the  STARPAC 
user  community.  We  are  grateful  for  the  many  valuable  comments  that  we  have 
received  on  early  drafts  of  the  STARPAC  documentation;  we  wish  especially  to 
thank  Paul  T.  Boggs,  Ginger  A.  Caldwell,  Sally  E.  Howe,  John  E.  Koontz,  James 
T.  Ringland,  Ralph  M.  Slutz,  and  Dominic  F.  Vecchia.  Finally,  we  wish  to 
thank  Lorna  Buhse  for  excellent  manuscript  support. 


Janet  R.  Donaldson 
Peter  V.  Tryon  (deceased) 
October  1985 


Contents 


Preface v 

1.  INTRODUCTION  TO  USING  STARPAC 1-1 

A.  Overview  of  STARPAC  and  Its  Contents- 1-1 

B.  Documentation  Conventions 1-1 

C.  A Sample  Program 1-2 

D.  Using  STARPAC 1-6 

D.l  The  PROGRAM  Statement 1-6 

D.2  The  Dimension  Statements 1-6 

D.3  The  CALL  Statements 1-8 

D.  4 STARPAC  Output.  ..  1-8 

D.  5 STARPAC  Error  Handling. 1-9 

D. 6  Common  Programming  Errors  When  Using  STARPAC 1-10 

2.  LINE  PRINTER  GRAPHICS 2-1 

A.  Introduction 2-1 

B . Subroutine  Descriptions.  2-1 

C.  Subroutine  Declaration  and  CALL  Statements 2-2 

D.  Dictionary  of  Subroutine  Arguments  and  COMMON  Variables....  2-11 

E.  Computational  Details 2-14 

F.  Examples 2-15 

3 . NORMAL  RANDOM  NUMBER  GENERATION.  3-1 

A.  Introduction 3-1 

B.  Subroutine  Descriptions... 3-1 

C.  Subroutine  Declaration  and  CALL  Statements 3-1 

D.  Dictionary  of  Subroutine  Arguments. 3-2 

E.  Computational  Methods............. 3-3 

F.  Example. 3-3 

G.  Acknowledgments.  3-6 

4.  HISTOGRAMS....... 4-1 

A . Introduction. 4-1 

B.  Subroutine  Descriptions 4-1 

C.  Subroutine  Declaration  and  CALL  Statements 4-1 

D.  Dictionary  of  Subroutine  Arguments 4-2 

E.  Computational  Methods 4-3 

E. l  Algorithms..... 4-3 

E.2  Computed  Results  and  Printed  Output 4-3 

F.  Example 4-5 

G.  Acknowledgments... 4-8 


5.  STATISTICAL  ANALYSIS  OF  A UNIVARIATE  SAMPLE 

A.  Introduction . 

B.  Subroutine  Descriptions 

C.  Subroutine  Declaration  and  CALL  Statements..... 

D.  Dictionary  of  Subroutine  Arguments  and  COMMON  Variables.... 

E.  Computational  Methods 

E.l  Algorithms 

E.2  Computed  Results  and  Printed  Output 

F . Example 

G.  Acknowledgments . . . 


6 . ONE-WAY  ANALYSIS  OF  VARIANCE 

A.  Introduction 

B.  Subroutine  Descriptions..... 

C.  Subroutine  Declaration  and  CALL  Statements.......... 

D.  Dictionary  of  Subroutine  Arguments  and  COMMON  Variables.... 

E.  Computational  Methods 

E .1  Algorithms  

E.2  Computed  Results  and  Printed  Output 

F . Example 

G . Acknow led  gme  nts. .........................  .................. 


7 . CORRELATION  ANALYSIS 

A . Introduction. 

B.  Subroutine  Descriptions.................................... 

C.  Subroutine  Declaration  and  CALL  Statements................. 

D.  Dictionary  of  Subroutine  Arguments  and  COMMON  Variables.... 

E o Comp  utat  xonal  Me  thods  .......  ......  .............. 

Eol  Algon t hms ..........  ....... .........  .««........©©..*.. 

E.2  Computed  Results  and  Printed  Output................... 

F . Example  . . . 

Go  Acknowledgments. .oo®o..«oo©o©«*o.©...©.*.««o...o.». ........ 


LINEAR  LEAST  SQUARES. 


A . Introduction 

B.  Subroutine  Descriptions...... 

C.  Subroutine  Declaration  and  CALL  Statements 

D.  Dictionary  of  Subroutine  Arguments  and  COMMON  Variables.... 

E.  Computational  Methods 

E.l  The  Linear  Least  Squares  Algorithm 

E.2  Computed  Results  and  Printed  Output 

F . Examples. 

G.  Acknowledgments.  


5-1 

5-1 

5-1 

5-1 

5-3 

5-8 

5-8 

5-8 

5-8 

5-11 


6-1 

6-1 

6-1 

6-1 

6-2 

6-3 

6-3 

6-3 

6-6 

6-9 


7-1 

7-1 

7-1 

7-1 

7-2 

7-3 

7-3 

7-3 

7-7 

7-11 


8-1 

8-1 
8-2 
8-2 
8-5 
8-9 
8-9 
8-9 
8-12 
8-2  3 


viii 


9.  NONLINEAR  LEAST  SQUARES 9-1 

A.  Introduction 9-1 

B.  Subroutine  Descriptions 9-2 

B.l  Nonlinear  Least  Squares  Estimation  Subroutines 9-2 

B .2  Derivative  Step  Size  Selection  Subroutines 9-3 

B.3  Derivative  Checking  Subroutines 9-4 

C.  Subroutine  Declaration  and  CALL  Statements 9-4 

D.  Dictionary  of  Subroutine  Arguments  and  COMMON  Variables....  9-10 

E.  Computational  Methods 9-20 

E.l  Algorithms 9-20 

E.l.a  Nonlinear  Least  Squares  Estimation 9-20 

E.l.b  Derivative  Step  Size  Selection 9-22 

E.l.c  Derivative  Checking 9-24 

E .2  Computed  Results  and  Printed  Output.............. 9-25 

E.2.a  The  Nonlinear  Least  Squares  Estimation 

Subroutines 9-2  5 

E.2.b  The  Derivative  Step  Size  Selection  Subroutines.  P-28 

E.2.c  The  Derivative  Checking  Subroutines 9-28 

F . Examples  9-2  9 

G.  Acknowledgments...... 9-49 

10.  DIGITAL  FILTERING.  10-1 

A.  Introduction. 10-1 

B.  Subroutine  Descriptions..... 10-1 

B.l  Symmetric  Linear  Filter  Subroutines 10-1 

B .2  Autoregressive  or  Difference  Linear  Filter 

Subroutines.  10-3 

B.3  Gain  and  Phase  Function  Subroutines 10-4 

C.  Subroutine  Declaration  and  CALL  Statements 10-4 

D.  Dictionary  of  Subroutine  Arguments  and  COMMON  Variables....  10-8 

E.  Computational  Methods.... 10-14 

E .1  Algorithms  . 10-14 

E .2  Computed  Results  and  Printed  Output 10-14 

F . Examples.  10-14 

G.  Acknowledgments.  . 10-20 

11.  COMPLEX  DEMODULATION........... 11-1 

A.  Introduction........... 11-1 

B.  Subroutine  Descriptions 11-1 

C.  Subroutine  Declaration  and  CALL  Statements 11-2 

D.  Dictionary  of  Subroutine  Arguments  and  COMMON  Variables....  11-2 

E.  Computational  Methods 11-4 

E.l  Algorithms 11-4 

E .2  Computed  Results  and  Printed  Output 11-5 

F.  Example 11-5 

G.  Acknowledgments 11-9 


12.  CORRELATION  AND  SPECTRUM  ANALYSIS 12-1 

A.  Introduction 12-1 

B.  Subroutine  Descriptions 12-1 

B.l  Correlation  Analysis..... 12-2 

B.l.a  Univariate  Series 12-2 

B.l.b  Bivariate  Series 12-3 

B .2  Spectrum  Estimation 12-4 

B .2  .a  Univariate  Series. 12-4 

B .2 .b  Bivariate  Series. 12-7 

C.  Subroutine  Declaration  and  CALL  Statements.. 12-7 

D.  Dictionary  of  Subroutine  Arguments  and  COMMON  Variables....  12-20 

E.  Computational  Methods 12-37 

E.l  Algorithms 12-37 

E.l.a  Correlation  Analysis 12-37 

E.l.b  Spectrum  Analysis................. 12-37 

E.2  Computed  Results  and  Printed  Output...................  12-38 

E.2.a  Correlation  Analysis.. 12-38 

E.2.b  Spectrum  Analysis 12-41 

F . Examples 12-44 

G.  Acknowledgments. ...........................................  12-77 

13.  ARIMA  MODELING 13-1 

A.  Introduction 13-1 

B . Subroutine  Descriptions. ...................................  13-3 

B.l  ARIMA  Estimation  Subroutines..................... 13-3 

B.2  ARIMA  Forecasting  Subroutines.........................  13-3 

C.  Subroutine  Declaration  and  CALL  Statements.......... 13-4 

D.  Dictionary  of  Subroutine  Arguments  and  COMMON  Variables....  13-5 

E . Computational  Methods ......................................  13-14 

E.l  Algorithms 13-14 

E.l.a  ARIMA  Estimation....... 13-14 

E.l.b  ARIMA  Forecasting..............................  13-15 

E.2  Computed  Results  and  Printed  Output............. 13-15 

E.2 .a  The  ARIMA  Estimation  Subroutines...............  13-15 

E.2.b  The  ARIMA  Forecasting  Subroutines.. 13-18 

F . Examples.  13-18 

G.  Acknowledgments 13-2  9 

Appendix  A A-l 

Appendix  B B-l 

Appendix  C .......  C-l 

References R-l 


x 


STARPAC 


The  Standards  Time  Series  and  Regression  Package 


Janet  R.  Donaldson  and  Peter  V.  Tryon 

National  Bureau  of  Standards 
Washington,  DC  20234 

STARPAC,  the  Standards  Time  Series  and  Regression  Package,  is  a 
library  of  Fortran  subroutines  for  statistical  data  analysis 
developed  by  the  Statistical  Engineering  Division  of  the  National 
Bureau  of  Standards,  Boulder,  Colorado.  Earlier  versions  of  this 
library  were  distributed  by  the  SED  under  the  name  STATLIB  [Tryon 
and  Donaldson,  1978],  STARPAC  incorporates  many  changes  to  STATLIB, 
including  additional  statistical  techniques,  improved  algorithms  and 
enhanced  portability. 

STARPAC  emphasizes  the  statistical  interpretation  of  results, 
and,  for  this  reason,  comprehensive  printed  reports  of  auxiliary 
statistical  information,  often  in  graphical  form,  are  automatically 
provided  to  augment  the  basic  statistical  computations  performed  by 
each  user-callable  STARPAC  subroutine.  STARPAC  thus  provides  the 
best  features  of  many  stand-alone  statistical  software  programs 
within  the  flexible  environment  of  a subroutine  library. 


Key  words:  data  analysis;  nonlinear  least  squares;  STARPAC; 

statistical  computing;  statistical  subroutine  library;  statistics; 
STATLIB;  time  series  analysis. 


I 


CHAPTER  1 


INTRODUCTION  TO  USING  STARPAC 


A.  Overview  of  STARPAC  and  Its  Contents 


STARPAC  is  a portable  library  of  approximately  150  user-callable  ANSI  '77 
Fortran  subroutines  for  statistical  data  analysis.  Designed  primarily  for 
time  series  analysis  and  for  nonlinear  least  squares  regression,  STARPAC  also 
includes  subroutines  for  normal  random  number  generation,  line  printer  plots, 
basic  statistical  analyses  and  linear  least  squares.  Emphasis  has  been  placed 
on  facilitating  the  interpretation  of  statistical  analyses,  and,  for  this 
reason,  comprehensive  printed  reports  of  auxiliary  statistical  information, 
often  in  graphical  form,  are  automatically  provided  to  augment  the  basic 
statistical  computations  performed  by  each  user-callable  STARPAC  subroutine. 
STARPAC  thus  provides  the  best  features  of  many  stand-alone  statistical 
software  programs  within  the  flexible  environment  of  a subroutine  library. 

STARPAC  is  designed  to  be  easy  to  use;  in  many  situations,  only  a few 
lines  of  elementary  Fortran  code  are  required  for  the  users'  main  programs.  A 
fundamental  STARPAC  philosophy  is  to  provide  two  or  more  user-callable 
subroutines  for  each  method  of  analysis:  one  which  minimizes  the  complexity 
of  the  CALL  statement,  automatically  producing  a comprehensive  printed  report 
of  the  results;  and  one  or  more  others  which  provide  user  control  of  the 
computations,  allow  suppression  of  all  or  part  of  the  printed  reports,  and/or 
provide  storage  of  computed  results  for  further  analyses. 

STARPAC  has  been  developed  and  is  maintained  by  the  Statistical 
Engineering  Division  of  the  National  Bureau  of  Standards,  Boulder,  Colorado. 
Users'  comments  and  suggestions,  which  have  had  significant  impact  already, 
are  highly  valued  and  always  welcomed.  Comments  and  suggestions  should  be 
directed  to: 


Janet  R.  Donaldson 
National  Bureau  of  Standards 
Mail  Code  714 
325  Broadway 
Boulder,  CO  80303. 


B.  Documentation  Conventions 


The  documentation  for  the  various  STARPAC  subroutine  families  uses  a 
standard  format  description  of  the  information  needed  to  use  a STARPAC 
subroutine,  including  one  or  more  examples. 

References  to  chapter  sections  within  the  STARPAC  documentation  are  made 
using  the  symbol  §,  and  refer  to  the  identified  section  within  the  current 
chapter  unless  explicitly  stated  otherwise.  Figures  are  identified  by  the 
section  in  which  they  occur.  For  example,  figure  C-2  refers  to  the  second 
figure  in  §C  of  this  chapter  (chapter  1). 


Names  of  INTEGER  and  REAL  STARPAC  subroutine  arguments  are  consistent 
with  the  implicit  Fortran  convention  for  specifying  variable  type.  That  is, 
variable  names  beginning  with  I through  N are  type  INTEGER  while  all  others 
are  type  REAL  unless  otherwise  explicitly  typed  DOUBLE  PRECISION  or  COMPLEX. 
All  dimensioned  variables  are  explicitly  declared  in  STARPAC  documentation  by 
means  of  INTEGER,  REAL,  DOUBLE  PRECISION,  or  COMPLEX  statements,  as 
appropriate.  The  convention  used  to  specify  the  dimension  statements  is 
discussed  below  in  §D.2. 

Currently,  only  the  single  precision  version  of  the  STARPAC  library  is 
supported  by  the  Statistical  Engineering  Division.  However,  a double 
precision  version  can  be  generated  relatively  easily.  The  precision  of  the 
STARPAC  library  is  indicated  in  the  printed  reports  generated  by  STARPAC:  an 
S following  the  STARPAC  version  number  in  the  output  heading  indicates  the 
single  precision  version  is  being  used,  while  a D indicates  the  double 
precision  version.  The  STARPAC  documentation  is  designed  for  use  with  both 
single  and  double  precision  versions.  Subroutine  arguments  which  are  double 
precision  in  both  versions  are  declared  DOUBLE  PRECISION;  similarly,  arguments 
which  are  single  precision  in  both  versions  are  declared  REAL.  Arguments 
whose  precision  is  dependent  upon  whether  the  single  or  double  precision 
version  of  STARPAC  is  being  used  are  declared  <real>.  If  the  double  precision 
version  of  the  STARPAC  library  is  being  used,  then  the  user  should  substitute 
DOUBLE  PRECISION  for  <real>;  if  the  single  precision  version  is  being  used, 
then  the  user  should  substitute  REAL  for  <real>.  Other  precision-dependent 
features  are  discussed  as  they  occur. 


C.  A Sample  Program 


The  sample  program  shown  in  figure  C-l  illustrates  the  use  of  STARPAC 
subroutines.  This  example  was  executed  on  the  CDC  CYBER  180/840  at  the  U.S. 
Department  of  Commerce  Boulder  Laboratories  under  the  NOS  2.3  operating  system 
using  a single  precision  version  of  the  STARPAC  library.  The  code  shown  is 
portable  ANSI  '77  Fortran.  Section  D below  uses  this  example  to  discuss 
Fortran  programming  as  it  relates  to  STARPAC. 


The  data  used  in  this  example  are  84  relative  humidity  measurements  taken 
at  Pikes  Peak,  Colorado.  STARPAC  subroutine  PP,  documented  in  chapter  2, 
plots  the  data  versus  time-order  (fig.  C-2)  and  STARPAC  subroutine  STAT, 
documented  in  chapter  4,  prints  a comprehensive  statistical  analysis  of  the 
data  (fig.  C-3). 


1-2 


OOOOOOOOOO 


MAIN  PROGRAM! 


PROGRAM  EXAMPL 


OAT  At 


DEMONSTRATE  STAT  ANO  PP  USING  SINGLE  PRECISION  VERSION  OF  STaRPAC 
RUN  ON  CYBER  190/840. 

OUTPUT  UNIT  IS  6 (AUTOMATICALLY  EOUATED  TO  FILE  T API 6 ON  CYRERS) 
ISEE  CHAPTER  1*  SECTION  D.43 

N.B.  DECLARATION  OF  Y AND  X MUST  BE  CHANGED  TO  DOUBLE  PRECISION 
IF  DOUBLE  PRECISION  VERSION  OF  STARPAC  IS  USED. 

REAL  Y(100),  X(IOO) 

DOUBLE  PRECISION  DSTAM100) 

C 

COMMON  /CSTAK/  OSTAK 
COMMON  /ERRCHK / I ERR 
C 

c define  ldstak,  the  length  of  dstak 

c 

IDSTAK  ■ 100 

c 

C READ  NUMBER  OF  OBSERVATIONS  INTO  N AND 

C DATA  INTO  VECTOR  Y 


READ  100*  N 

READ  101*  ( Y ( I ) » I-1*N> 

C 

C CREATE  A VECTOR  OF  QROER  INDICES  IN  X 


C 


DO  10  I-l*N 
X( I)  - I 
10  CONTINUE 
C 

C PRINT  TITLE*  PLOT  OF  DATA  ANO  ERROR  INDICATOR 

C 

WRITE  (6*  102) 

CALL  PP  t Y * X*  N) 

WRITE  (6*  101)  IERR 

C 

C PRINT  TITLE*  STATISTICAL  ANALYSIS  OF  DATA  ANO  ERROR  INDICATOR 

C 

WRITE  (6*  102) 

CALL  STAT  (T*  N*  LOSTAK) 

WRITE  (6*  103)  IERR 

C 

STOP 

c 

C FORMAT  STATEMENTS 

C 


100  FORMAT 

101  FORMAT 

102  FORMAT 

103  FORMAT 
END 


(19) 

(12F7.4) 

( UOAVIS-HARRI SON  PIKES  PEAK  RELATIVE  HUMIOITY  DATA8! 
(•  IERR  • •»  ID 
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0.6007 

0.6087 

0.6086 

0.6134 

0.6108 

0.6138 

0.6129 

0.6122 

0.6110 

0.6104 

0. 7213 

Oo  707a 

0.7021 

0.7004 

0.6981 

0.7242 

0.7268 

0.7418 

0.7407 

0.7199 

0.6229 

0.6294 

0.6292 

0.6267 

0.6218 

0.6178 

0.6216 

0.6192 

0.6191 

0.6290 

0.6188 

0.6233 

0.6229 

0.6204 

0.6207 

0.6166 

0.6141 

0.6291 

0.6231 

0.6222 

0.6292 

0.6308 

0.6376 

0.6330 

0.6303 

0.6301 

0.6390 

0.6423 

0.6300 

0.6260 

0.6292 

0.6298 

0.6290 

0.6262 

0. 9992 

0.9991 

0.6314 

0.6440 

0. 6439 

0.6326 

0.6192 

0.6417 

0.6412 

0.6930 

0.6411 

0.6199 

0.6344 

0.6623 

0.6276 

0.6307 

0.6394 

0.6197 

0.6193 

0.6140 

0.6318 

0.6284 

0.6162 

0.6292 

0.6349 

0.6344 

0.6361 

0.6373 

0.6137 

0.6383 

Figure  C-l 

STARPAC  sample  program  and  data 
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NOTE  - ITENS  IN  PARENTHESES  REFER  TO  PA6E  NUNBER  IN  NBS  HANDBOOK  91  I NATREll A*  19661 
I ERR  - 0 


D.  Using  STARPAC 


The  following  subsections  provide  general  information  needed  when  using 
STARPAC,  including  a discussion  of  Fortran  programming  as  it  relates  to 
STARPAC  usage.  Although  only  elementary  knowledge  of  Fortran  is  required  to 
use  STARPAC,  users  may  still  have  to  consult  with  a Fortran  text  and/or  their 
Computing  Center  staff  when  questions  arise. 


D. 1 The  PROGRAM  Statement 


The  PROGRAM  statement  is  used  to  name  the  user's  main  program.  The  name 
EXAMPL  is  assigned  to  the  main  program  in  this  example.  The  program  name 
cannot  be  the  name  of  any  variable  in  the  user's  main  program  and,  in 
addition,  cannot  be  the  name  of  any  other  subroutine  or  function  called  during 
execution  of  the  user's  code.  Specifically,  it  cannot  be  the  name  of  any 
subroutine  within  STARPAC.  To  ensure  that  the  name  of  a STARPAC  subroutine  is 
not  inadvertently  chosen  for  the  name  of  the  main  program,  users  should 
consult  with  the  local  installer  of  STARPAC  to  obtain  a list  of  the  STARPAC 
subroutine  names. 


D.2  The  Dimension  Statements 


The  user's  program  must  include  dimension  statements  to  define  the  sizes 
and  types  of  the  vectors,  matrices  and  three-dimensional  arrays  required  by 
each  STARPAC  subroutine  used;  STARPAC  itself  has  no  inherent  upper  limit  on 
problem  size. 

Within  the  STARPAC  documentation  for  the  subroutine  declaration  and  CALL 
statements,  italicized  lowercase  identifiers  in  the  dimension  statements 
represent  integer  constants  which  must  equal  or  exceed  the  value  of  the 
identically-spelled  uppercase  argument.  For  example,  if  the  documentation 
specifies  the  minimum  dimension  of  a variable  as  <real>  XM (n,m)y  and  if  the 
number  of  observations  N is  15,  and  the  number  of  columns  of  data  M is  3,  then 
(assuming  the  single  precision  version  of  STARPAC  is  being  used)  the  minimum 
array  size  is  given  by  the  dimension  statement  REAL  XM(15,3). 

The  exact  dimensions  assigned  to  some  vectors  and  matrices  must  be 
supplied  in  the  CALL  statements  to  some  STARPAC  subroutines.  For  example,  the 
argument  IXM  is  defined  as  "the  exact  value  of  the  first  dimension  of  the 
matrix  XM  as  declared  in  the  calling  program."  Continuing  the  example  from 
the  preceding  paragraph,  if  the  statement  REAL  XM(20,5)  is  used  to  dimension 
the  matrix  XM  for  a particular  subroutine,  and  IXM  is  an  argument  in  the  CALL 
statement,  then  IXM  must  have  the  value  20  regardless  of  the  value  assigned  to 
the  variable  N. 
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Many  STARPAC  subroutines  require  a work  area  for  internal  computations. 
This  work  area  is  provided  by  the  DOUBLE  PRECISION  vector  DSTAK.  The  rules 
for  defining  DSTAK  are  as  follows. 

1.  Programs  which  call  subroutines  requiring  the  work  vector  DSTAK  must 
include  the  statements 

DOUBLE  PRECISION  DSTAK  (Idstak) 

COMMON  / CSTAK/  DSTAK 

where  Idstak  indicates  the  integer  constant  used  to  dimension  DSTAK. 

2.  Since  all  STARPAC  subroutines  use  the  same  work  vector,  the  length  of 
DSTAK  must  equal  or  exceed  the  longest  length  required  by  any  of  the 
individual  STARPAC  subroutines  called  by  the  user's  program. 

3.  The  length,  LDSTAK,  of  the  work  vector  DSTAK  must  be  specified  in  the 
CALL  statement  of  any  STARPAC  subroutine  using  DSTAK  to  enable  STARPAC 
to  verify  that  there  will  be  sufficient  work  area  for  the  problem. 

It  is  recommended  that  a variable  LDSTAK  be  set  to  the  length  of  DSTAK, 
and  that  this  variable  be  used  in  each  CALL  statement  requiring  the  length  of 
DSTAK  to  be  specified.  Then,  if  a future  modification  to  the  user's  program 
requires  the  length  of  DSTAK  to  be  changed,  the  only  alterations  required  in 
the  existing  code  would  be  to  the  DOUBLE  PRECISION  dimension  statement  and  to 
the  statement  which  assigns  the  length  of  DSTAK  to  LDSTAK. 

STARPAC  manages  its  work  area  using  subroutines  modeled  after  those  in 
ACM  Algorithm  528:  Framework  for  a Portable  Library  [Fox  et  al.  1978a] . 

Although  STARPAC  and  the  Framework  share  the  same  COMMON  for  their  work  areas, 
there  are  differences  between  the  STARPAC  management  subroutines  and  those  of 
the  Framework.  In  particular,  the  STARPAC  management  subroutines 
re-initialize  DSTAK  each  time  the  user  invokes  a STARPAC  subroutine  requiring 
work  area,  destroying  all  data  previously  stored  in  DSTAK;  the  Framework  only 
initializes  DSTAK  the  first  time  any  of  its  management  subroutines  are 
invoked,  preserving  work  area  allocations  still  in  use.  Thus,  users  must  be 
cautious  when  utilizing  STARPAC  with  other  libraries  which  employ  the 
Framework,  such  as  PORT  [Fox  et  al.  1978b]. 

The  sample  program  shown  in  figure  C-l  provides  an  example  of  the  use  of 
dimensioned  variables  with  STARPAC.  The  REAL  vector  Y,  used  by  both 
subroutines  PP  and  STAT,  contains  the  84  relative  humidity  measurements;  its 
minimum  length,  N (the  number  of  observations),  is  84.  The  REAL  vector  X used 
by  subroutine  PP  contains  the  corresponding  time  order  indices  of  the  data; 
its  minimum  length  is  also  84.  The  DOUBLE  PRECISION  vector  DSTAK  contains  the 
work  area  needed  by  STAT  for  intermediate  computations;  its  minimum  length,  49 
in  this  case,  is  defined  in  §D  of  chapter  4.  In  this  example,  the  dimensions 
of  Y,  X,  and  DSTAK,  are  each  100,  exceeding  the  required  minimum  values. 
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D.3  The  CALL  Statements 


The  STARPAC  CALL  statement  arguments  provide  the  interface  for  specifying 
the  data  to  be  used,  controlling  the  computations,  and  providing  space  for  any 
returned  results.  The  CALL  statements  used  in  the  example  (fig.  C-l)  are 
CALL  PP(Y,  X,  N)  and  CALL  STAT(Y,  N,  LDSTAK).  Note  that  scalar  arguments  may 
be  specified  either  by  a variable  preset  to  the  desired  value,  as  was  done  in 
the  example,  or  by  the  actual  numerical  values.  For  example,  CALL 
PP(Y,  X,  84)  and  CALL  STAT(Y,  84,  100)  could  have  been  used  instead  of  the 
forms  shown.  We  recommend  using  variables  rather  than  the  actual  numerical 
values  in  order  to  simplify  future  changes  in  the  program.  When  variables  are 
used,  changes  need  to  be  made  in  only  one  place;  numerical  values  have  to  be 
changed  every  place  they  occur.  The  use  of  variables  can  also  clarify  the 
meaning  of  the  program. 


D. 4 STARPAC  Output 

Most  STARPAC  subroutines  produce  extensive  printed  reports,  freeing  the 
user  from  formatting  and  printing  all  statistics  of  interest.  The  standard 
output  device  is  used  for  these  reports.  The  user  has  the  options  of  titling 
the  reports  and  changing  the  output  device. 

The  first  page  of  the  report  from  each  STARPAC  subroutine  does  not  start 
on  a new  page.  This  allows  the  user  to  supply  titles.  For  example, 

WRITE  (6,  100) 

100  FORMAT  ( '1DAVIS-HARRIS0N  PIKES  PEAK  RELATIVE  HUMIDITY  DATA’) 

CALL  PP  (Y,  X,  N) 

will  print  the  title  DAVIS-HARRISON  PIKES  PEAK  RELATIVE  HUMIDITY  DATA  on  the 
top  line  of  a new  page,  immediately  preceding  the  plot  as  shown  in  figure  C-2. 
Users  should  note  that  titles  more  than  one  line  in  length  can  cause  a printed 
report  designed  for  one  page  to  extend  beyond  the  bottom  of  the  page. 

The  unit  number,  IPRT,  of  the  output  device  used  by  STARPAC  is  returned 
by  STARPAC  subroutine  IPRINT.  Users  can  change  the  output  device  unit  number 
by  including  with  their  program  a subroutine  IPRINT  which  will  supersede  the 
STARPAC  subroutine  of  the  same  name.  The  subroutine  must  have  the  form 

SUBROUTINE  IPRINT(IPRT) 

IPRT  = u 

RETURN 

END 

where  u is  an  integer  value  specifying  the  output  unit  to  which  all  STARPAC 
output  will  be  written. 
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D. 5 STARPAC  Error  Handling 


STARPAC  provides  extensive  error-checking  facilities  which  include  both 
printed  reports  and  a program-accessible  error  flag  variable.  There  are 
essentially  two  types  of  errors  STARPAC  can  detect. 

The  first  type  of  error  involves  incorrect  problem  specification,  i.e., 
one  or  more  of  the  input  arguments  in  the  subroutine  statement  has  an  improper 
value.  For  example,  the  number  of  observations,  N,  might  have  an  obviously 
meaningless  non-positive  value.  In  the  case  of  improper  problem  specification 
STARPAC  generates  a printed  report  identifying  the  subroutine  involved,  the 
error  detected,  and  the  proper  form  of  the  subroutine  CALL  statement.  The 
latter  is  provided  because  improper  input  is  often  the  result  of  an 
incorrectly  specified  subroutine  argument  list. 

A second  type  of  error  can  be  thought  of  as  a computation  error:  either 
the  initiated  calculation  cannot  be  completed  or  the  results  from  the  called 
subroutine  are  questionable.  For  example,  when  the  least  squares  model  and 
data  are  found  to  be  singular,  the  desired  computations  cannot  be  completed; 
when  one  or  more  of  the  standardized  residuals  from  a least  squares  fit  cannot 
be  computed  because  the  standard  deviation  of  the  residual  is  zero,  the 
results  of  the  error  estimates  from  the  least  squares  regression  may  be 
questionable.  If  a computation  error  is  detected,  STARPAC  generates  a report 
which  identifies  the  error,  and,  to  aid  the  user  in  determining  the  cause  of 
the  error,  summarizes  the  completed  results  in  a printed  report. 

STARPAC  error  reports  cannot  be  suppressed,  even  when  the  normal  output 
from  the  STARPAC  subroutine  has  been  suppressed.^  Because  of  this,  users 
seldom  have  to  consciously  handle  STARPAC  error  conditions  in  their  code. 

When  proper  execution  of  the  user's  program  depends  on  knowing  whether  or 
not  an  error  has  been  detected,  the  error  flag  can  be  examined  from  within  the 
user's  code.  When  access  to  the  error  flag  is  desired,  the  statement 

COMMON  /ERRCHK/  IERR 

must  be  placed  with  the  Fortran  declaration  statements  in  the  user's  program. 
Following  the  execution  of  a STARPAC  subroutine,  the  variable  IERR  will  be  set 
to  zero  if  no  errors  were  detected,  and  to  a nonzero  value  otherwise;  the 
value  of  IERR  may  indicate  the  type  of  error  [e.g. , see  chapter  9,  §D, 
argument  IERR].  If  the  CALL  statement  is  followed  with  a statement  of  the. 
f orm 


IF  (IERR  ,NE.  0)  STOP 

then  the  program  will  stop  when  an  error  is  detected.  (In  figure  C-l,  the 
value  of  IERR  is  printed  following  each  CALL  statement  to  show  the  value 
returned. ) 


^STARPAC  output  must  be  directed  to  a separate  output  device  [see  §D.4]  when 
users  do  not  want  any  STARPAC  reports  displayed  under  any  conditions. 
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D. 6 Common  Programming  Errors  When  Using  STARPAC 


STARPAC  error-checking  procedures  catch  many  programming  errors  and  print 
informative  diagnostics  when  such  errors  are  detected.  However,  there  are 

some  errors  which  STARPAC  cannot  detect.  The  more  common  of  these  are 
discussed  below. 

1.  The  most  common  error  involves  array  dimensions  which  are  too  small. 

Although  certain  arguments  are  checked  by  STARPAC  to  verify  that  array 

dimensions  are  adequate,  if  incorrect  information  is  supplied  to 

STARPAC,  or  if  the  dimension  of  an  array  which  is  not  checked  is  too 
small,  the  program  will  produce  erroneous  results  and/or  will  stop 
prematurely.  Users  should  check  the  dimension  statements  in  their 
program  whenever  difficulties  are  encountered  in  using  STARPAC. 

2.  The  second  most  common  error  involves  incorrect  CALL  statements,  that 

is,  CALL  statements  in  which  the  STARPAC  subroutine  name  is 

misspelled,  the  arguments  are  incorrectly  ordered,  one  or  more 
arguments  are  omitted,  or  the  argument  types  (INTEGER,  REAL,  DOUBLE 
PRECISION,  and  COMPLEX)  are  incorrect.  Users  having  problems  using 
STARPAC  should  carefully  check  their  declaration  and  CALL  statements 
to  verify  that  they  agree  with  the  documentation. 

3.  The  third  most  common  error  involves  incorrect  specification  of  the 
work  vector  DSTAK.  Programs  which  call  STARPAC  subroutines  requiring 
work  area  must  include  both  the  DOUBLE  PRECISION  statement  dimension 
DSTAK  and  the  COMMON  /CSTAK/  DSTAK  statement. 

4.  The  final  common  error  involves  user-supplied  subroutines  which  have 
the  same  name  as  a subroutine  in  the  STARPAC  library.  Users  should 
consult  with  the  local  installer  of  STARPAC  to  obtain  a list  of  all 
STARPAC  subroutine  names.  This  list  can  then  be  used  to  ensure  that  a 
STARPAC  subroutine  name  has  not  been  duplicated. 

Users  who  have  not  found  the  cause  of  a problem  after  checking  the 
possibilities  mentioned  above  should  consult  with  their  Computing  Center 
advisers. 


CHAPTER  2 


LINE  PRINTER  GRAPHICS 


A.  Introduction 

STARPAC  contains  36  subroutines  for  producing  2 basic  styles  of  line 
printer  plots. 

The  first,  called  a page  plot,  uses  a single  11  x 14  inch  page  of  line 
printer  paper. 

The  second,  called  a vertical  plot,  is  designed  for  plotting  time  series. 
The  user  specifies  only  the  y-axis  values  since  the  x-axis  values  (independent 
variable)  are  assumed  to  be  equally  spaced  and  ordered  consecutively.  The 
independent  variable  in  the  resulting  plot  is  oriented  vertically  and  the  plot 
will  continue  over  as  many  pages  as  necessary  to  plot  one  point  per  line. 

Within  these  two  basic  styles  the  user  has  many  options,  including 
controlling  the  plot  symbol,  plotting  multivariate  values,  designating  missing 
data,  using  log  scales  and  specifying  plot  limits  and  plot  size. 

Users  are  directed  to  §B  for  a brief  description  of  the  subroutines.  The 
actual  declaration  and  CALL  statements  are  given  in  §C  and  the  subroutine 
arguments  are  defined  in  §D.  The  algorithms  used  and  output  produced  by  these 
subroutines  are  discussed  in  §E.  Sample  programs  and  their  output  are  shown 
in  §F . 


B . Subroutine  Descriptions 

PP  (.Page  Plot)  and  VP  (Vertical  Plot)  are  the  simplest  of  the  STARPAC 
line  printer  plot  subroutines.  For  both,  plot  limits  are  automatically  set  by 
the  range  of  the  data  and  other  control  parameters  are  set  to  the  default 
values  given  in  §D.  The  remaining  plotting  subroutines  are  named  by  adding 
letters  to  the  beginning  and/or  end  of  PP  and  VP. 

© Prefix  S (e.g. , SPP)  indicates  the  user  controls  the  plot  symbol  for 
each  point. 

© Prefix  M indicates  the  subroutine  will  accept  multivariate  y-axis 
values  (e.g.,  MPP). 

© Suffix  M subroutines  allow  data  with  missing  observations  to  be  plotted 
(e.g.,  VPM ) . 

© Suffix  L indicates  log  scales  can  be  used  (e.g.,  PPL). 

© Suffix  C subroutines  allow  control  of  the  parameters  which  specify  the 
plot  limits,  size,  scale,  etc.  (e.g.,  VPC). 


2-1 


The 

following  table,  which  indicates  the 

capabilities  of 

each 

of  the 

STARPAC 

plotting 

subroutines, 

can 

be  used 

to  select 

f rom 

the  available 

subroutines.  Subroutine  declaration 

and  CALL 

statements  are 

given 

in  §C , 

listed  in 

the  same 

order  as  in 

the  table. 

Plot 

Symbol 

Multiple 

Page 

Vertical 

Missing 

Log 

Control 

Control 

Y-Axis 

Plot 

Plot 

Data 

Scale 

Parameters 

Name 

(S) 

(M) 

(PP) 

(VP) 

(M) 

(L) 

(c) 

PP 

/ 

PPL 

/ 

V 

/ 

V 

PPC 

/ 

/ 

/ 

PPM 

/ 

/ 

PPML 

/ 

/ 

/ 

PPMC 

/ 

✓ 

/ 

/ 

SPP 

~T~ 

/ 

SPPL 

/ 

/ 

/ 

SPPC 

/ 

/ 

/ 

/ 

SPPM 

/ 

/ 

/ ' 

SPPML 

/ 

✓ 

/ 

/ 

SPPMC 

/ 

/ 

/ 

/ 

/ 

MPP 

MPPL 

MPPC 

MPPM 

MPPML 

MPPMC 


VP 

VPL 

VPC 

VPM 

VPML 

VPMC 


SVP 

7 

“7“ 

SVPL 

/ 

/ 

/ 

SVPC 

/ 

/ 

/ 

/ 

SVPM 

/ 

/ 

/ 

SVPML 

/ 

/ 

✓ 

/ 

SVPMC 

/ 

/ 

/ 

/ 

/ 

MVP 

~7~ 

7 

MVPL 

/ 

/ 

/ 

MV  PC 

/ 

/ 

/ 

/ 

MV  PM 

/ 

/ 

/ 

MVPML 

/ 

/ 

/ 

/ 

MV  PMC 

/ 

/ 

/ 

/ 

/ 

C.  Subroutine 

Declaration  and 

CALL 

Statements 

NOTE:  Argument  definitions 

and  s 

ample  programs 

are 

given 

in  §D  and  §F, 

respective ly . 

The  conventions 

used 

to  present  the 

following 

declaration  and 

CALL  statments 

are  given  in  chapter 

1 , §B  and  §D . 

Page  Plots 


PP:  Print  Y versus  X scatterplot ; linear  axes;  default  control  values  and 

axis  limits;  no  missing  values  allotted 

<real>  Y(n),  X(n) 

# 

CALL  PP  (Y,  X,  N) 

PPL:  Print  Y versus  X scatterplot;  log  or  linear  axes;  default  control 

values  and  axis  limits;  no  missing  values  allotted 
<real>  Y(n),  X(rc) 

S 

CALL  PPL  (Y,  X,  N,  ILOG) 

PPC : Print  Y versus  X scatterplot;  log  or  linear  axes;  user-supplied 

control  values  and  axis  limits;  no  missing  values  allotted 

<real>  Y(n),  X(n),  YLB , YUB,  XLB , XUB 

S 

CALL  PPC  (Y,  X,  N,  ILOG,  ISIZE,  NOUT,  YLB,  YUB,  XLB,  XUB) 

PPM:  Print  Y versus  X scatterplot;  linear  axes;  default  control  values  and 

axis  limits;  missing  values  allowed 

<real>  Y(n),  YMISS,  X(n),  XMISS 
CALL  PPM  (Y,  YMISS,  X,  XMISS,  N) 

PPML:  Print  Y versus  X scatterplot;  log  or  linear  axes;  default  control 

values  and  axis  limits;  missing  values  allowed 

<real>  Y(n),  YMISS,  X(n),  XMISS 


CALL  PPML  (Y,  YMISS,  X,  XMISS,  N,  ILOG) 
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PPMC: 


Print  Y versus  X scatterplot ; log  or  linear  oozes;  user-supplied, 
control  values  and  axis  limits;  missing  values  allowed 

<real>  Y(n),  YMISS,  X(n),  XMISS,  YLB , YUB , XLB , XUB 


CALL  PPMC  (Y,  YMISS,  X,  XMISS,  N,  ILOG,  ISIZE,  NOUT,  YLB,  YUB, 
1 XLB,  XUB) 


SPP:  Print  Y versus  X scatterplot  with  individual  plot  symbols  specified 

by  user;  linear  axes;  default  control  values  and  axis  limits;  no 
missing  values  allowed 

<real>  Y(n),  X(n) 

INTEGER  ISYM(rc) 


CALL  SPP  (Y,  X,  N,  ISYM) 


SPPL:  Print  Y versus  X scatterplot  with  individual  plot  symbols  specified 

by  user;  log  or  linear  axes;  default  control  values  and  axis  limits; 
no  missing  values  allowed 

<real>  Y(n),  X(n) 

INTEGER  ISYM(n) 


CALL  SPPL  (Y,  X,  N,  ISYM,  ILOG) 


SPPC:  Print  Y versus  X scatterplot  with  individual  plot  symbols  specified 

by  user;  log  or  linear  axes;  user- supplied  control  values  and  axis 
limits;  no  missing  values  allowed 

<real>  Y(n),  X(n),  YLB,  YUB,  XLB,  XUB 
INTEGER  ISYM(n) 


CALL  SPPC  (Y,  X,  N,  ISYM,  ILOG,  ISIZE,  NOUT,  YLB,  YUB,  XLB,  XUB) 
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SPPM: 


Print  Y versus  X seatterplot  with  individual  plot  symbols  specified 
by  user;  linear  axes ; default  control  values  and  axis  limits;  missing 
values  allowed 


<real>  Y(n),  YMISS,  X(n),  XMISS 
INTEGER  ISYM(n) 


CALL  SPPM  (Y,  YMISS,  X,  XMISS,  N,  ISYM) 


SPPML:  Print  Y versus  X seatterplot  with  individual  plot  symbols  specified 

by  user;  log  or  linear  axis;  default  control  values  and  axis  limits; 
missing  values  allowed 

<real>  Y(n),  YMISS,  X(n),  XMISS 
INTEGER  ISYM(n) 

CALL  SPPML  (Y,  YMISS,  X,  XMISS,  N,  ISYM,  ILOG) 


SPPMC:  Print  Y versus  X seatterplot  with  individual  plot  symbols  specified 

by  user;  log  or  linear  axes;  user- supplied  control  values  and  axis 
limits;  missing  values  allowed 

<real>  Y(n),  YMISS,  X(n),  XMISS,  YLB , YUB,  XLB , XUB 
INTEGER  ISYM(n) 


CALL  SPPMC  (Y,  YMISS,  X,  XMISS,  N,  ISYM,  ILOG,  ISIZE,  NOUT,  YLB, 
1 YUB,  XLB,  XUB) 


MPP:  Print  plot  of  multiple  Y vectors  versus  a common  X vector;  linear 

axes;  default  control  values  and  axis  limits;  no  missing  values 
allowed 

<real>  YM (n,m)t  X(n) 


CALL  MPP  (YM,  X,  N,  M,  IYM) 
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MPPL:  Print  plot  of  multiple  Y vectors  versus  a common  X vector;  log  or 

linear  axes;  default  control  values  and  axis  limits;  no  missing  values 
allowed 

<real>  YM( ntm)>  X(n) 


CALL  MPPL  (YM,  X,  N,  M,  IYM , ILOG) 

MPPC : Print  plot  of  multiple  Y vectors  versus  a common  X vector;  log  or 

linear  axes;  user- supplied  control  values  and  axis  limits;  no  missing 
values  allowed 

<real>  YM(n,m),  X(n),  YLB , YUB,  XLB,  XUB 


CALL  MPPC  (YM,  X,  N,  M,  IYM,  ILOG,  ISIZE,  NOUT,  YLB,  YUB,  XLB, 

1 XUB) 

MPPM:  Print  plot  of  multiple  Y vectors  versus  a common  X vector;  linear 

axes;  default  control  values  and  axis  limits;  missing  values  allowed 

<real>  YM (n,m),  YMMISS(m),  X(n),  XMISS 


CALL  MPPM  (YM,  YMMISS,  X,  XMISS,  N,  M,  IYM) 


MPPML:  Print  plot  of  multiple  Y vectors  versus  a common  X 

linear  axes;  default  control  values  and  axis  limits; 
allowed 

<real>  YM (n,m),  YMMISS(m),  X(n),  XMISS 

S 

CALL  MPPML  (YM,  YMMISS,  X,  XMISS,  N,  M,  IYM,  ILOG) 


MPPMC:  Print  plot  of  multiple  Y vectors  versus  a common  X 

linear  axes;  user-supplied  control  values  and  axis  limits;  missing 
values  allowed 

<real>  YM {n,m) , YMMISS(m),  X(n),  XMISS,  YLB,  YUB,  XLB,  XUB 


CALL  MPPMC  (YM,  YMMISS,  X,  XMISS,  N,  M,  IYM,  ILOG,  ISIZE,  NOUT, 
1 YLB,  YUB,  XLB,  XUB) 


vector;  log  or 
missing  values 


vector;  log  or 
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Vertical  Plots 


VP:  Print  vertical  plot  of  Y versus  input  order;  linear  axes;  default 

control  values  and  axis  limits;  no  missing  values  allowed 

<real>  Y(n) 

t 

CALL  VP  (Y,  N,  NS) 

VPL:  Print  vertical  plot  of  Y versus  input  order;  log  or  linear  horizontal 

(Y)  axis;  default  control  values  and  axis  limits;  no  missing  values 
allowed 

<real>  Y (n ) 

1 

CALL  VPL  (Y,  N,  NS,  ILOG) 

VPC:  Print  vertical  plot  of  Y versus  input  order;  log  or  linear  horizontal 

(Y)  axis;  user-supplied  control  values  and  axis  limits;  no  missing 
values  allowed 

<real>  Y (n  ) , YLB , YUB , XLB , XINC 
i 

CALL  VPC  (Y,  N,  NS,  ILOG,  ISIZE,  IRLIN,  IBAR,  YLB,  YUB,  XLB, 

1 XINC) 

VPM:  Print  vertical  plot  of  Y versus  input  order;  linear  axis;  default 

control  values  and  axis  limits;  missing  values  allowed 

<real>  Y(n),  YMISS 

CALL  VPM  (Y,  YMISS,  N,  NS) 

VFML:  Print  vertical  plot  of  Y versus  input  order;  log  or  linear  horizontal 

(Y)  axis;  default  control  values  and  axis  limits;  missing  values 
allowed 

<real>  Y (n ) , YMISS 

CALL  VPML  (Y,  YMISS,  N,  NS,  ILOG) 
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VPMC:  Print  vertical  plot  of  Y versus  input  order;  log  or  linear  horizontal 

(Y)  axis ; user- supplied  control  values  and  axis  limits ; missing  values 
allowed 

<real>  Y(n),  YMISS,  YLB , YUB , XLB , XINC 


CALL  VPMC  (Y,  YMISS,  N,  NS,  ILOG,  ISIZE,  IRLIN,  IBAR,  YLB,  YUB, 
1 XLB,  XINC) 


SVP:  Print  vertical  plot  of  Y versus  input  order  with  individual  plot 

symbols  specified  by  user;  linear  axis;  default  control  values  and 
axis  limits;  no  missing  values  allowed 

<real>  Y(n) 

INTEGER  ISYM(n) 


CALL  SVP  (Y,  N,  NS,  ISYM) 


SVPL:  Print  vertical  plot  of  Y versus  input  order  with  individual  plot 

symbols  specified  by  user;  log  or  linear  horizontal  (Y)  axis;  default 
control  values  and  axis  limits;  no  missing  values  allowed 

<real>  Y(n) 

INTEGER  ISYM(n) 


CALL  SVPL  (Y,  N,  NS,  ISYM,  ILOG) 


SVPC:  Print  vertical  plot  of  Y versus  input  order  with  individual  plot 

symbols  specified  by  user;  log  or  linear  horizontal  (Y)  axis; 
user-supplied  control  values  and  axis  limits;  no  missing  values 
allowed 

<real>  Y(n),  YLB,  YUB,  XLB,  XINC 
INTEGER  ISYM(n) 


CALL  SVPC  (Y,  N,  NS,  ISYM,  ILOG,  ISIZE,  IREFLN,  IBAR,  YLB,  YUB, 
1 XLB,  XINC) 
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SVPM: 


SVPML: 


SVPMC: 


MVP: 


Print  vertical  plot  of  Y versus  input  order  with  individual  plot 
symbols  specified  by  user;  linear  axis ; default  control  values  and 
axis  limits;  missing  values  allowed 

<real>  Y(n),  YMISS 
INTEGER  ISYM(tt) 

CALL  SVPM  (Y,  YMISS,  N,  NS,  ISYM) 


Print  vertical  plot  of  Y versus  input  order  with  individual  plot 
symbols  specified  by  user;  log  or  linear  horizontal  (Y)  axis;  default 
control  values  and  axis  limits;  missing  values  allowed 

<real>  Y(n),  YMISS 
INTEGER  ISYM(n) 


CALL  SVPML  (Y,  YMISS,  N,  NS,  ISYM,  ILOG) 


Print  vertical  plot  of  Y versus  input  order  with  individual  plot 
symbols  specified  by  user;  log  or  linear  horizontal  (Y)  axis; 
user-supplied  control  values  and  axis  limits;  missing  values  allowed 

<real>  Y(n),  YMISS,  YLB , YUB , XLB , XING 
INTEGER  ISYM(n) 


CALL  SVPMC  (Y,  YMISS,  N,  NS,  ISYM,  ILOG,  ISIZE,  IRLIN,  IBAR,  YLB, 
1 YUB,  XLB,  XING) 


Print  vertical  plot  of  multiple  Y vectors  versus  input  order;  linear 
axis;  default  control  values  and  horizontal  (Y)  axis  limits;  no 
missing  values  allowed 

<real>  YM(n3m) 


CALL  MVP  (YM,  N,  M,  IYM , NS) 
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MVPL:  Print  vertical  plot  of  multiple  Y vectors  versus  input  order;  log  or 

linear  horizontal  (Y)  axis;  default  control  values  and  axis  limits;  no 
missing  values  allowed 

<real>  YM (nym) 


CALL  MVPL  (YM,  N,  M,  IYM,  NS,  ILOG) 


MVPC:  Print  vertical  plot  of  multiple  Y vectors  versus  input  order;  log  or 

linear  horizontal  (Y)  axis;  user- supplied  control  values  and  axis 
limits;  no  missing  values  allowed 

<real>  YM YLB , YUB , XLB , XINC 


CALL  MVPC  (YM,  N,  M,  IYM,  NS,  ILOG,  ISIZE,  YLB,  YUB,  XLB,  XINC) 


MVPM:  Print  vertical  plot  of  multiple  Y vectors  versus  input  order;  linear 

axis;  default  control  values  and  axis  limits;  missing  values  allowed 

<real>  YM (n}m),  YMMISS(m) 


CALL  MVPM  (YM,  YMMISS,  N,  M,  IYM,  NS) 


MVPML:  Print  vertical  plot  of  multiple  Y vectors  versus  input  order;  log  or 

linear  horizontal  (Y)  axis;  default  control  values  and  axis  limits; 
missing  values  allowed 

<real>  YM (n,  m ) , YMMISS(m) 


CALL  MVPML  (YM,  YMMISS,  N,  M,  IYM,  NS,  ILOG) 


MVPMC:  Print  vertical  plot  of  multiple  Y vectors  versus  input  order;  log  or 

linear  horizontal  (Y)  axis;  user- supplied  control  values  and  axis 
limits;  missing  values  allowed 

<real>  YM(n,m),  YMMISS  (tf?) , YLB,  YUB,  XLB,  XINC 


CALL  MVPMC  (YM,  YMMISS,  N,  M,  IYM,  NS,  ILOG,  ISIZE,  YLB,  YUB, 
1 XLB,  XINC) 
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D.  Dictionary  of  Subroutine  Arguments  and  COMMON  Variables 


NOTE: 


I BAR 


I ERR 


I LOG 


IRLIN 


— > indicates  that  the  argument  is  input  to  the  subroutine  and  that 
the  input  value  is  preserved; 

< — indicates  that  the  argument  is  returned  by  the  subroutine; 

<->  indicates  that  the  argument  is  input  to  the  subroutine  and  that 
the  input  value  is  overwritten  by  the  subroutine; 

indicates  that  the  argument  is  input  to  some  subroutines  and  is 

returned  by  others; 

***  indicates  that  the  argument  is  a subroutine  name; 

**•  indicates  that  the  variable  is  passed  via  COMMON. 

— > The  indicator  variable  used  to  designate  whether  a vertical  plot 
is  to  be  a bar  plot  or  not.  Bar  plots  connect  the  plotted  points 
to  the  reference  line  [see  argument  IRLIN]  with  a string  of  plot 
symbols.  [See,  e.g.,  chapter  12,  figure  F-lc. ] If  IBAR  > 1,  the 
plot  is  a bar  plot.  If  IBAR  < 0,  it  is  not.  The  default  value  is 
IBAR  = 0.  When  IBAR  is  not  an  argument  in  the  subroutine  CALL 
statement  the  default  value  is  used. 

'**  An  error  flag  returned  in  COMMON  /ERRCHK/.  [See  chapter  1,  § D . 5 . ] 
Note  that  using  (or  not  using)  the  error  flag  will  not  affect  the 
printed  error  messages  that  are  automatically  provided. 

IERR  = 0 indicates  that  no  errors  were  detected  and  that  the  plot 
was  completed  satisfactorily. 

IERR  = 1 indicates  that  improper  input  was  detected  or  that  some 
error  prevented  the  plot  from  being  completed. 

— > The  indicator  variable  used  to  designate  whether  the  axes  are  to 
be  on  a log  or  linear  scale.  ILOG  is  a two-digit  integer,  pq , 
where  the  value  of  p is  used  to  designate  the  scale  of  the  x-axis 
and  the  value  of  q is  used  to  designate  the  scale  of  the  y-axis. 
If  p = 0 (q  = 0)  the  x-axis  (y-axis)  is  on  a linear  scale;  if 
p * 0 (q  * 0)  the  x-axis  (y-axis)  is  on  a log  scale.  For  vertical 

plots,  the  value  of  q is  used  to  specify  the  scale  on  the 

horizontal-axis  and  the  value  of  p is  ignored.  The  default  value 
is  ILOG  = 0,  corresponding  to  linear  scale  for  both  the  x-axis  and 
the  y-axis.  When  ILOG  is  not  an  argument  in  the  subroutine  CALL 
statement  the  default  value  is  used. 

— •>  The  indicator  variable  used  to  designate  whether  zero  or  the 

series  mean  is  to  be  plotted  as  a reference  line  on  the  vertical 

plots  or  whether  no  reference  line  should  be  used.  If  IRLIN  < -1, 
no  reference  line  is  plotted.  If  IRLIN  = 0,  a reference  line  is 
plotted  showing  the  location  of  zero  on  the  plot.  If  IRLIN  > 1,  a 

reference  line  is  plotted  showing  the  series  mean.  The  default 
value  is  IRLIN  = -1.  When  IRLIN  is  not  an  argument  in  the 
subroutine  CALL  statement  the  default  value  is  used. 
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[SIZE  — > The  indicator  variable  used  to  designate  the  size  of  a page  plot. 

ISIZE  is  a two-digit  integer,  pq , where  the  value  of  p is  used  to 
designate  the  size  of  the  x-axis  and  the  value  of  q is  used  to 
designate  the  size  of  the  y-axis.  If  p = 0 (q  = 0)  the  x-axis 
(y-axis)  is  the  maximum  possible,  101  columns  (51  rows),  i.e.,  101 
(51)  plot  positions.  If  p t 0 (q  t 0)  the  x-axis  (y-axis)  is  half 
the  maximum,  or  51  columns  (26  rows).  For  vertical  plots,  the 
value  of  q is  used  to  specify  the  size  of  the  horizontal-axis  and 
the  value  of  p is  ignored.  The  default  value  is  ISIZE  = 0, 
corresponding  to  a plot  of  51  rows  by  101  columns.  When  ISIZE  is 
not  an  argument  in  the  subroutine  CALL  statement  the  default  value 
is  used. 


ISYM  — > The  vector  of  dimension  at  least  N that  contains  the  values 
designating  the  plotting  symbol  to  be  used  for  each  point.  The 
plot  symbols  designated  by  each  possible  integer  value  are  given 
below. 


IYM 


ISYM(*  )<  1 + + 
I SYM ( « )=  2 -►  • 
I SYM(*  )=  3 + * 
I SYM  ( ° )=  4 - 

I SYM  ( • )=  5 A 
I SYM  ( • )=  6 > B 
I SYM  ( * )=  7 * C 
I SYM ( » )=  8 -»■  D 


ISYM(  • )=  9 -»■  E 
ISYM( ® )=10  + F 
ISYM(  » ) = 11  G 

ISYM(  • ) = 1 2 ->•  H 
ISYM( • )=1 3 * I 
ISYM( ® )=14  * J 
I SYM  ( ® ) = 1 5 + K 


ISYM( • ) = 1 6 -»■  L 
ISYM( « )=1 7 + M 
ISYM(  • ) = 18  + N 
ISYM( • ) = 19  -►  0 
ISYM(  • )=20  +■  P 
ISYM( • )=2 1 * Q 
ISYM(  • )=22  ■*  R 


ISYM(»  )=23  + S 
ISYM(»  )=24  T 
I SYM  ( • )=25  -v  U 
ISYM(*  )=26  + V 
I SYM ( ® )=27  W 

ISYM(»  )=28  ^ Y 
ISYM(»  )>  29  Z 


matrix  YM  as 


> The  exact  value  of  the  first  dimension  of  the 
specified  in  the  calling  program. 


M 


-->  The  number  of  columns  of  data  in  YM. 


N — > The  number  of  observations. 


NOUT  — > The  number  of  points  falling  outside  the  plot  limits  that  are  to 

be  listed  following  the  plot.  If  NOUT  > 1 , a message  giving  the 
total  number  of  points  falling  outside  the  plot  limits  and  a list 
of  the  coordinates  of  these  points  (up  to  a maximum  of  NOUT  or  50, 
whichever  is  smaller)  is  printed.  If  NOUT  = 0,  only  a message 
listing  the  number  of  points  falling  outside  the  limits  is 
printed.  If  NOUT  < 0,  no  points  are  listed  and  no  message  is 
given.  The  default  value  is  NOUT  = 0.  When  NOUT  is  not  an 
argument  in  the  subroutine  CALL  statement  the  default  value  is 
used. 


NS  — > The  sampling  frequency  of  the  points  plotted  on  a vertical  plot. 

If  NS  = 1,  every  point  is  plotted;  if  NS  = 2,  every  second  point 
is  plotted;  if  NS  = 3,  every  third  point  is  plotted,  etc.  The 
default  value  is  NS  = 1.  When  NOUT  < 0 or  NS  is  not  an  argument 
in  the  subroutine  CALL  statement  the  default  value  is  used. 
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X 


dimension  at  least  N that  contains 


the  x-axis 


— > The  vector  of 
values. 

XINC  — > The  increment  to  be  used  for  labeling  the  x-axis  (i.e.,  the 

vertical-axis)  on  vertical  plots.  The  x-axis  labels  are  XLB , 
XLB  + NS»XINC,  XLB  + 2»NS*XINC,  etc.  The  default  value  is 
XINC  = 1.0.  When  XINC  is  not  an  argument  in  the  subroutine  CALL 
statement  the  default  value  is  used. 

XLB  -->  The  lower  bound  for  the  x-axis. 

For  page  plots: 

The  default  value  is  the  smallest  x-axis  value  within  the  range 
of  the  y-axis  values  to  be  plotted.  If  XLB  > XUB , the  default 
value  is  used. 

For  vertical  plots: 

The  default  value  is  1.0. 


For  both  page  and  vertical  plots,  when  XLB  is  not  an  argument  in 
the  subroutine  CALL  statements  the  default  value  is  used.  (The 
plot  limits  may  be  adjusted  slightly  from  the  user-supplied  values 
when  the  plotting  subroutine  uses  a log  scale. ) 

XMISS  — > The  missing  value  code  used  within  the  vector  X to  indicate  that  a 

value  is  missing.  The  user  must  indicate  missing  observations  by 
putting  the  missing  value  code  in  place  of  each  missing 
observation.  Missing  data  are  not  indicated  on  page  plots  in  any 
way . 

XUB  — > The  upper  bound  for  the  x-axis.  The  default  value  is  the  largest 

x-axis  value  within  the  range  of  the  y-axis  values  to  be  plotted. 

If  XLB  > XUB  or  XUB  is  not  an  argument  in  the  subroutine  CALL 

statement  the  default  value  is  used.  (The  plot  limits  may  be 
adjusted  slightly  from  the  user-supplied  value  when  the  plotting 
subroutines  use  a log  scale. ) 

Y -->  The  vector  of  dimension  at  least  N that  contains  the  y-axis 

values. 

YLB  -->  The  lower  bound  for  the  y-axis.  The  default  value  is  the  smallest 

y-axis  value  within  the  range  of  the  x-axis  values  to  be  plotted. 

If  YLB  > YUB  or  YLB  is  not  an  argument  in  the  subroutine  CALL 

statement  the  default  value  is  be  used.  (The  plot  limits  may  be 
adjusted  slightly  from  the  user-supplied  value  when  the  plotting 
subroutines  use  a log  scale. ) 

YM  — > The  matrix  of  dimension  at  least  N by  M whose  columns  each  contain 

one  of  the  M sets  of  N observations  to  be  plotted  against  a common 
X vector. 
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YMISS 


— > The  missing  value  code  used  within  the  vector  Y to  indicate  a 
value  is  missing.  The  user  must  indicate  missing  observations  by 
putting  the  missing  value  code  in  place  of  each  missing 
observation.  Missing  data  are  indicated  on  vertical  plots  by  the 
word  "MISSING"  next  to  the  right  axis  of  the  appropriate  line. 
Missing  data  are  not  indicated  on  page  plots  in  any  way. 

YMMISS  — > The  vector  of  dimension  at  least  M that  contains  the  codes  used 
within  each  of  the  M columns  of  YM  to  indicate  a value  is  missing, 
where  the  first  element  of  YMMISS  is  the  missing  value  code  for 
the  first  column  of  YM,  etc.  The  user  must  indicate  missing 
observations  by  putting  the  appropriate  missing  value  code  in 
place  of  each  missing  observation.  Missing  data  are  indicated  on 
vertical  plots  by  the  word  "MISSING"  next  to  the  right  axis  of  the 
appropriate  line.  Missing  data  are  not  indicated  on  page  plots  in 
any  way. 

YUB  — > The  upper  bound  for  the  y-axis.  The  default  value  is  the  largest 

y-axis  value  within  the  range  of  the  x-axis  values  to  be  plotted. 
If  YLB  YUB  or  YUB  is  not  an  argument  in  the  subroutine  CALL 
statement  the  default  value  is  used.  (The  plot  limits  may  be 
adjusted  slightly  from  the  user-supplied  value  when  the  plotting 
subroutines  use  a log  scale. ) 


E . Computational  Details 

Plotting  Symbols.  The  plotting  symbol  used  depends  on  the  type  of  plot 
and  whether  or  not  more  than  one  point  falls  on  a given  plot  position.  If  two 
to  nine  points  fall  on  a single  plot  position,  the  integer  corresponding  to 
the  number  of  points  is  used  as  the  plotting  symbol.  When  10  or  more  values 
fall  on  a single  position  the  plotting  symbol  X is  used.  This  is  the  only  way 
that  integers  or  X are  used  as  plot  symbols. 

Subroutines  without  an  S or  M prefix  use  the  plotting  symbol  + to 
indicate  one  point  on  a single  printer  position. 

For  subroutines  with  an  S prefix  the  user-supplied  vector  ISYM  of  integer 
values  is  used  to  specify  the  plotting  symbol  for  each  data  point.  The 
Fourier  spectrum  plot  shown  in  chapter  12,  figure  F-3b,  is  an  example  of  this 
option. 

Subroutines  with  an  M prefix  use  a different  letter  as  the  plot  symbol 
for  each  column  of  the  matrix  of  the  dependent  variables  (y-axis):  A for  the 
first,  B for  the  second,  ...,  Z for  columns  25  and  beyond,  with  X still  only 
used  to  indicate  that  10  or  more  points  fell  on  a single  plot  position. 
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Continuity  of  Vertical  Plots.  Normally,  a line  printer  will 
automatically  provide  margins  at  the  top  and  bottom  of  each  page,  causing  a 
break  in  the  continuity  of  a vertical  plot  or  any  other  output  continuing  over 
two  or  more  pages.  However,  these  automatic  page-ejects  can  be  suppressed  by 
the  user  on  many  systems.  Appendix  A gives  the  control  sequence  necessary  to 
suppress  automatic  page-ejects  on  a Cyber  computer.  Users  of  other  systems 
should  consult  their  Computer  Center  staff  for  any  equivalent  method 
available. 


F . Examples 


The  example  program  of  figure  F-la  uses  MPP  to  display  the  12  years  of 
monthly  airline  data  listed  on  page  531  of  Box  and  Jenkins  [1976]  versus 
month.  The  year  is  indicated  by  the  plotting  symbol  (A  = 1949,  B = 1950, 
etc.).  Figure  F-lb  shows  the  output  from  this  program. 

Other  examples  of  STARPAC  plots  can  be  found  in  the  output  of  many  of  the 
subroutines  discussed  elsewhere.  The  output  from  the  complex  demodulation 
subroutines  includes  a simple  vertical  plot  (VP)  (chapter  11,  figure  F-lb)  and 
a vertical  plot  of  multivariate  data  (MVPC)  (chapter  11,  figure  F-lc);  the 
output  from  the  autocorrelation  and  cross  correlation  subroutines  includes 
vertical  plots  using  the  bar  plot,  option  (VPC)  (chapter  12,  figure  F-lc);  and 
the  output  from  the  Fourier  spectrum  subroutines  (chapter  12,  figure  F-3b)  is 
produced  using  a symbol  plot  (SPPC). 


MAIN  PROGRAMI 


“ROGRAN  EXAHPL 


DATA  I 


C 

C DEMONSTRATE  MPP  USING  SINGLE  PRECISION  VERSION  OF  STARPAC 

C RUN  ON  CYBER  180/BA0. 

C 

C OUTPUT  UNIT  IS  6 (AUTOMATICALLY  EQUATED  TO  FILE  TAPE6  ON  CYBERS) 

C CSEE  CHAPTER  1>  SECTION  D.43 

C 

C N.B.  DECLARATION  OF  X AND  YM  MUST  BE  CHAN6ED  TO  DOUBLE  PRECISION  IF 

C DOUBLE  PRECISION  VERSION  OF  STARPAC  IS  USED. 

C 

REAL  X ( 20  ) « YN  ( 20»  2 0 ) 

C 

C SPECIFY  NECESSARY  DIMENSIONS 

C 

I YM  « 20 

C 

C READ  NUMBER  OF  OBSERVATIONS  AND  NUMBER  OF  COLUMNS  OF  DATA 

C X-AXIS  VALUES 

C Y-AXIS  VALUES 

C 

READ  100»  N»  M 

READ  101#  (X(Ii»  I«1#N» 

READ  101#  ( t YM ( I # J ) # X«1#N)#  J«»l,Mi 

C 

C PRINT  TITLE  AND  CALL  MPP  FOR  PLOT 

C 

WRITE  (6 # 102) 

CALL  MPP  (YM,  X#  N*  M#  I YM ) 

C 

STOP 

C 

C FORMAT  STATEMENTS 

C 

100  FORMAT  (215) 

101  FORMAT  J12F6.1) 

102  FORMAT  (URiSUlTS  OF  STARPAC  PLOT  SUBROUTINE  HPP») 

END 
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Example  program  using  MPP 
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Example  of  MPP  output 


I 

p 

p 

p 

fl 

(1 

III 

III 

III 

III 

III 

III 

111 

1 

I 

II 
II 

n 

[i 


CHAPTER  3 


NORMAL  RANDOM  NUMBER  GENERATION 


A.  Introduction 


STARPAC  contains  two  subroutines  for  generating  pseudo-random  numbers 
(noise)  which  obey  a normal  probability  law  with  mean  p and  standard  deviation 
a.  Such  random  numbers  are  often  useful  for  evaluating  data  analysis 
procedures  or  computer  programs. 

Users  are  directed  to  §B  for  a brief  description  of  the  subroutines.  The 
declaration  and  CALL  statements  are  given  in  §C  and  the  subroutine  arguments 
are  defined  in  §D.  The  algorithm  used  by  these  subroutines  is  discussed  in 
§E.  A sample  program  showing  the  use  of  these  subroutines  is  given  in  §F. 


B .  Subroutine  Descriptions 


STARPAC  subroutine  NRAND  generates  a vector  of  standard  (zero  mean  and 
unit  standard  deviation)  normal  (Gaussian)  random  numbers.  There  is  no 

printed  output  from  this  subroutine. 

STARPAC  subroutine  NRANDC  generates  Gaussian  noise  with  mean  p and 
standard  deviation  a using  the  transformation 

z = ay  + p 


where 

y is  a standard  normal  psuedo-random  number; 

p is  the  desired  mean  (see  §D,  argument  YMEAN);  and 

o is  the  desired  standard  deviation  (see  §D,  argument  SIGMA). 

There  is  no  printed  output  from  NRANDC. 


C .  Subroutine  Declaration  and  CALL  Statements 

NOTE:  Argument  definitions  and  a sample  program  are  given  in  §D  and  §F, 
respectively.  The  conventions  used  to  present  the  following  declaration  and 
CALL  statments  are  given  in  chapter  1,  §B  and  D. 
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NRAND:  Generate  a vector  of  normal  pseudo-random  numbers  with  zero  mean  and 

unit  standard  deviation 

<real>  Y (n) 

CALL  NRAND  (Y,  N,  ISEED) 

NRANDC:  Generate  a vector  of  normal  pseudo-random  numbers  with  mean  YMEAN  and 

standard  deviation  SIGMA 

<real>  Y («) 

CALL  NRANDC  (Y,  N,  ISEED,  YMEAN,  SIGMA) 


D.  Dictionary  of  Subroutine  Arguments 


NOTE:  — ■>  indicates  that  the  argument  is  input  to  the  subroutine  and  that 

the  input  value  is  preserved; 

<--  indicates  that  the  argument  is  returned  by  the  subroutine; 

<->  indicates  that  the  argument  is  input  to  the  subroutine  and  that 
the  input  value  is  overwritten  by  the  subroutine; 

- — indicates  that  the  argument  is  input  to  some  subroutines  and  is 
returned  by  others; 

***  indicates  that  the  argument  is  a subroutine  name; 

* * • indicates  that  the  variable  is  passed  via  COMMON, 


IERR  ...  An  error  flag  returned  in  COMMON  /ERRCHK/.  [See  chapter  1,  §D.5.] 
Note  that  using  (or  not  using)  the  error  flag  will  not  affect  the 
printed  error  messages  that  are  automatically  provided. 

IERR  = 0 indicates  that  no  errors  were  detected. 

IERR  = 1 indicates  that  improper  input  was  detected. 

ISEED  ' — > The  basis  for  the  pseudo-random  number  generation. 


For  ISEED  t 0,  use  of  the  same  value  of  ISEED  will  always 
generate  the  same  data  set. 

For  ISEED  = 0,  a different  data  set  will  be  produced  by  each  call 
to  NRAND  or  NRANDC  in  the  user's  program,  although 
the  numbers  generated  will  not  differ  from  run  to 
run. 


N 


— > The  number  of  random  numbers  to  be  generated. 
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SIGMA  — > The  standard  deviation  of  the  generated  random  numbers. 

Y < — The  vector  of  dimension  at  least  N that  contains  the 

normal  pseudo-random  numbers. 

YMEAN  — > The  mean  of  the  generated  random  numbers. 

E . Computational  Methods 


generated 


The  normal  pseudo-random  number  generation  procedure  is  that  of  Marsaglia 
and  Tsang  [1984].  The  same  pseudo-random  numbers  (to  within  final  round-off 
error)  will  be  generated  on  any  computer.  The  code  was  written  by  Boisvert 
and  Kahanar  of  the  National  Bureau  of  Standards  Scientific  Computing 
Division. 


F . Example 

The  sample  program  shown  in  figure  F-la  illustrates  the  use  of  both  NRAND 
and  NRANDC.  NRAND  is  used  to  generate  a standard  normal  pseudo-random  sample 
of  size  50  from  a normal  population  with  zero  mean  and  unit  standard 
deviation.  NRANDC  is  then  used  to  generate  a sequence  of  normal  pseudo-random 
numbers  with  a mean  of  4 and  standard  deviation  0.5.  The  same  seed  is  used 
for  both  NRAND  and  NRANDC.  Therefore,  the  values  generated  by  NRANDC  are 
YMEAN  plus  SIGMA  times  the  values  generated  by  NRAND,  i.e. , 

YMEAN (I, 2)  = YMEAN  + S IGMA*YME AN (1,1)  f or  I = 1 , . . . , N. 

The  generated  random  numbers  are  displayed  using  STARPAC  plot  subroutine  MVP. 
Figure  F-lb  shows  the  output  from  MVP.  There  is  no  output  from  NRAND  and 
NRANDC. 
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PROGRAM  EXAMPL 

DEMONSTRATE  NR  AND  AND  NRANDC  AND  DISPLAT  RESULTS  WITH  MVP  USING 
SINGLE  PRECISION  VERSION  OF  STARPAC  RUN  ON  CYBER  180/8*0. 

OUTPUT  UNIT  IS  6 (AUTOMATICALLY  EQUATED  TO  FILE  TAPE6  ON  CYBERS) 
[SEE  CHAPTER  1»  SECTION  D.A1 

N.B.  DECLARATION  OF  YM  MUST  BE  CHANGED  TO  DOUBLE  PRECISION  IF 
DOUBLE  PRECISION  VERSION  OF  STARPAC  IS  USED. 

REAL  YH ( 100»  2 ) 

SPECIFY  NECESSARY  DIMENSIONS 
I YH  - 100 
SET  THE  SEED 

THE  NUMBER  OF  VALUES  TO  BE  GENERATED 
THE  NUMBER  OF  SETS  OF  DATA  TO  BE  GENERATED 

ISEEO  » 931 
N • 90 
M ■ 2 

GENERATE  STANDARD  NORMAL  PSEUDO-RANDOM  NUMBERS  INTO  COLUMN  l OF  YH 
CALL  NR  AND  (YM(l#lJj>  N»  ISEEO » 

GENERATE  NORMAL  PSEUDO-RANDOM  NUMBERS  WITH  MEAN  AeO  AND 
STANDARD  DEVIATION  0.5  INTO  COLUMN  2 OF  YM 

YHEAN  * A.O 
SIGMA  * 0.9 

CALL  NRANDC  !YMU»2I«>  N»  ISElDg  YHEAN?  SIGNAI 

PRINT  TITLE  AND  CALL  MVP  TO  PLOT  RESULTS 

WRITE  (6?  1008 

CALL  MVP  «YM»  N»  Mg  IYH9 

STOP 

FORMAT  STATEMENTS 

100  FORMAT  C'lRfSULTS  OF  STARPAC  NORMAL  PSUIDO-RANDOM  NUMBER  * t 

1 » GENERATION  SUBROUTINES  » t 

2 * DISPLAYED  WITH  STARPAC  PLOT  SUBROUTINE  MVP*  > 

END 


Figure  F-la 


Example  program  using  NRAND,  NRANDC  and  MVP 
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Example  of  NRAND  and  NRANDC  results  displayed  using  MVP 
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CHAPTER  4 


HISTOGRAMS 


A.  Introduction 


STARPAC  contains  two  subroutines  for  producing  histograms.  Both 
subroutines  produce  a one-page  printout  which  includes,  in  addition  to  the 
histogram,  a number  of  summary  statistics  (mean,  median,  standard  deviation, 
cell  fractions,  etc. ) and  several  tests  for  normality. 

Users  are  directed  to  §B  for  a brief  description  of  the  subroutines.  The 
declaration  and  CALL  statements  are  given  in  §C  and  the  subroutine  arguments 
are  defined  in  §D.  The  algorithms  used  and  output  produced  by  these 
subroutines  are  discussed  in  §E.  Sample  programs  and  their  output  are  shown 
in  §F . 


B .  Subroutine  Descriptions 

HIST  provides  the  analysis  described  in  §A  using  a preset  procedure  for 
choosing  the  number  of  cells.  The  lower  and  upper  bounds  of  the  histogram  are 
chosen  from  the  range  of  the  observations. 

HISTC  provides  the  same  analysis  as  HIST  but  allows  the  user  to  specify 
the  number  of  cells  and  the  upper  and  lower  cell  boundaries.  Statistics  are 
based  only  on  the  data  within  the  user-supplied  bounds. 


C .  Subroutine  Declaration  and  CALL  Statements 

NOTE;  Argument  definitions  and  sample  programs  are  given  in  §D  and  §F, 
respectively.  The  conventions  used  to  present  the  following  declaration  and 
CALL  statments  are  given  in  chapter  1,  §B  and  D. 

HIST:  Compute  and  print  a histogram  and  summary  statistics , with  automatic 

selection  of  number  of  cells  and  cell  boundaries 

<real>  Y(n) 

DOUBLE  PRECISION  DSTAK (Idstak) 

COMMON  / CSTAK/  DSTAK 


CALL  HIST  (Y,  N,  LDSTAK) 


HISTC:  Compute  and  print  a histogram  and  summary  statistics  with  user 

control  of  number  of  cells  and  cell  boundaries 

<real>  Y(n) 

DOUBLE  PRECISION  DSTAK (Idstak) 

COMMON  /CSTAK/  DSTAK 


CALL  HISTC  (Y,  N,  NCELL,  YLB , YUB , LDSTAK) 


D.  Dictionary  of  Subroutine  Arguments 


NOTE:  — > indicates  that  the  argument  is  input  to  the  subroutine  and  that 

the  input  value  is  preserved; 

< — indicates  that  the  argument  is  returned  by  the  subroutine; 

<->  indicates  that  the  argument  is  input  to  the  subroutine  and  that 
the  input  value  is  overwritten  by  the  subroutine; 

---  indicates  that  the  argument  is  input  to  some  subroutines  and  is 
returned  by  others; 

***  indicates  that  the  argument  is  a subroutine  name; 

*  *  * * indicates  that  the  variable  is  passed  via  COMMON. 


DSTAK.  c“  The  DOUBLE  PRECISION  vector  in  COMMON  /CSTAK/  of  dimension  at 
least  LDSTAK.  DSTAK  provides  workspace  for  the  computations.  The 
first  LDSTAK  locations  of  DSTAK  will  be  overwritten  during 
subroutine  execution. 

IERR  * * * An  error  flag  returned  in  COMMON  /ERRCHK/.  [See  chapter  1,  §D . 5 . ] 
Note  that  using  (or  not  using)  the  error  flag  will  not  affect  the 
printed  error  messages  that  are  automatically  provided. 

IERR  = 0 indicates  that  no  errors  were  detected. 

IERR  = 1 indicates  that  improper  input  was  detected. 

LDSTAK  — > The  length  of  the  DOUBLE  PRECISION  workspace  vector  DSTAK.  LDSTAK 
must  equal  or  exceed  the  appropriate  value  given  below,  where  if 
the  single  precision  version  of  STARPAC  is  being  used  P = 0.5, 
otherwise  P = 1.0.  [See  chapter  1,  § B . ] 

For  HIST:  LDSTAK  > (17+N)/2  + 26-P 

For  HISTC:  LDSTAK  > (17+N)/2  + max( NCELL,  26)«P 

N — > The  number  of  observations. 

NCELL  — > The  number  of  cells  in  the  histogram.  If  NCELL  < 0 or  NCELL  is 

not  an  argument  in  the  subroutine  CALL  statement  the  subroutine 
will  choose  the  number  of  cells. 
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the  observed 


Y — > The  vector  of  dimension  at  least  N that  contains 

data. 

YLB  — > The  lower  bound  for  constructing  the  histogram.  The  interval 

[YLB,  YUB ] is  divided  into  NCELL  increments.  If  YLB  > YUB , the 

lower  and  upper  bounds  for  constructing  the  histogram  will  be  the 
minimum  and  maximum  observations. 

YUB  — > The  upper  bound  for  constructing  the  histogram.  The  interval 

[YLB,  YUB]  is  divided  into  NCELL  increments.  If  YLB  > YUB,  the 

lower  and  upper  bounds  for  constructing  the  histogram  will  be  the 
minimum  and  maximum  observations. 

E . Computational  Methods 


E . 1 Algorithms 

The  code  and  output  for  the  histogram  subroutines  are  modeled  after  early 
versions  of  MINITAB  [Ryan  et  al.  1974] . 


E „ 2 Computed  Results  and  Printed  Output 

The  output  from  the  histogram  family  of  subroutines  includes  a summary  of 
the  input  data  in  addition  to  the  actual  histogram.  This  summary  includes  the 
following  information,  where  the  actual  output  headings  are  given  by  the 
underlined,  uppercase  phrases.  Results  which  correspond  to  subroutine  CALL 
statements  arguments  are  identified  by  the  argument  name  in  uppercase  (not 
underlined).  In  the  formulas,  x\ , X2,  ...»  x^  denotes  the  ordered 

observations  of  Y such  that  YLB  < Y(i)  < YUB,  i = 1,  ...,  N,  i.e.  , x^  is  the 

smallest  observation  of  Y such  that  YLB  < Y(i),  x^  is  the  largest  observation 
of  Y such  that  Y(i)  < YUB,  etc.  The  value  of  expressions  enclosed  in  square 
brackets,  e.g. , [(k/2)  +1],  is  the  largest  integer  less  than  or  equal  to  the 
value  of  the  expression. 

© NUMBER  OF  OBSERVATIONS,  N 

© MINIMUM  OBSERVATION 


o MAXIMUM  OBSERVATION 
© HISTOGRAM  LOWER  BOUND,  YLB 
© HISTOGRAM  UPPER  BOUND,  YUB 
o NUMBER  OF  CELLS,  NCELL 
o OBSERVATIONS  USED,  k,  where 

k = the  number  of  observations  for  which 
YLB  < Y(i)  < YUB,  i = 1,  ...,  N 
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o MIN.  OBSERVATION  USED,  xL  , where 


1 

= the  smallest  observation  such  that  YLB  < Y(i),  i = 1,  N p 

o MAX.  OBSERVATION  USED,  xk,  where 

xk  = the  largest  observation  such  that  Y(i)  < YUB,  i = 1,  ...,  N J 


o MEAN  VALUE,  xmean,  where 


k 

^Snean  k I xi 
i = l 


o MEDIAN  VALUE,  Xmedian’  where 

xmedian  = x[(k+l)/2]  if  k is  odd 

xmedian  = °*5*(x[k/2]  + x[(k/2)  + 1]) *  1 
© 25  PCT  TRIMMED  MEAN,  xtritn,  where 

k~[k/4] 

xtrim  = [k“(2*  [k/^])]"1  l x£ 

i=l+ [k/ 4 ] 


• STANDARD  DEVIATION,  s,  where 


k 9 1/2 

s = ( (k— 1 £ (x-i  ^ean'  ) 

i=l 


© MEAN  DEV. /STD.  DEV. , r,  where 


k 

r - (s»k)  £ lxi”xmearJ 

i=l 

• SQRT(BETA  ONE) , &l1/2,  where 


Bl  = ( (k-l)3.s6)-1  ( l (xi-xmean)3)2.k 

i = l 


© BETA  TWO , g2,  where, 


8 2 = ( (k— 1 )2  « s4 ) 1 l (xi"xmean)4.k 

i = l 


V 

V 

k is  even 

11 

I 

I 

I 

II 

9 

I 

a 

9 

I 

I 
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Information  provided  for  each  cell,  £ = 1,  NCELL,  of  the  histogram 

includes  the  following. 

® INTERVAL  MID  POINT,  cmid,  where 

Cmid  = YLB  + (YUB-YLB)/ (2* NCELL) 

• CUM.  FRACT. , the  cumulative  fraction  of  the  observations  which  are  in 

cells  1 through  £ 

• 1-CUM.  FRACT. , the  cumulative  fraction  of  the  observations  which  are 

in  cells  £ through  NCELL 

9 CELL  FRACT. , the  fraction  of  the  observations  which  are  in  cell  £ 

9 NO.  OBS. , the  actual  number  of  observations  which  are  in  cell  £ . 

The  histogram  itself  displays  the  actual  number  of  observations  in  each 
cell  when  the  largest  number  of  observations  per  cell  does  not  exceed  50. 
When  the  largest  number  of  observations  per  cell  does  exceed  50  then  the 
histogram  displays  the  cell  fraction. 

F . Example 

The  example  program  of  figure  F-la  uses  HIST  to  analyze  the  39 
measurements  of  the  velocity  of  light  shown  on  page  81  of  Mandel  [1964].  The 
output  from  HIST  is  shown  in  figure  F-lb. 
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MAIN  PROGRAM! 


PROGRAM  EXAMPL 


DATA! 


C 

C DEMONSTRATE  HIST  USING  SIN6LI  PRECISION  VERSION  OP  STARPAC 

C RUN  ON  CYBER  1BO/8AO. 

C 

C OUTPUT  UNIT  IS  6 (AUTOMATICALLY  EQUATED  TO  FILE  TAPES  ON  CYBERS) 

C C SEE  CHAPTER  1#  SECTION  D.4J 

C 

C N.B.  DECLARATION  OF  Y MUST  BE  CHANGED  TO  DOUBLE  PRECISION  IF 

C DOUBLE  PRECISION  VERSION  OF  STARPAC  IS  USED* 

C 

REAL  YC2O0S 

DOUBLE  PRECISION  OSTAM2O0) 

C 

COMMON  /CSTAK/  DSTAK 
C 

C SPECIFY  NECESSARY  DIMENSIONS 

C 

LDSTAK  ® 20© 

C 

C READ  NUMBER  OF  OBSERVATIONS 

C OBSERVED  DATA 

C 

READ  100#  M 

READ  101#  IYCIJ#  X-1#N> 

C 

C PRINT  TITLE  AND  CALL  HIST  TO  ANAL  VIE  RESULTS 

C 

WRITE  (6#  102 1 
CALL  HIST  ( Y#  N#  LDSTAK I 
C 

STOP 

C 

C FORMAT  STATEMENTS 

C 

100  FORMAT  CIS! 

101  FORMAT  U3F9.1) 

101  FORMAT  (URESULTS  OF  STARPAC  HISTOGRAM  SUBROUTINE  HIST') 

END 
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Example  of  HIST  output 


G.  Acknowledgments 


The  code  and 
early  versions  of 


output 

MINITAB 


f 


or  the  histogram  subrout 
[Ryan  et  al.  1974] . 


ines  is  modeled  on 


that  in 
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CHAPTER  5 


STATISTICAL  ANALYSIS  OF  A UNIVARIATE  SAMPLE 


A.  Introduction 


STARPAC  contains  4 subroutines  for  performing  a comprehensive  statistical 
analysis  of  a univariate  sample.  They  each  compute  53  different  statistics 
which  summarize  the  sample  through  measures  of  location  (mean,  median,  etc), 
measures  of  dispersion  (standard  deviation,  mean  deviation,  etc. ) and 
diagnostic  features  such  as  tests  for  outliers,  non-normality,  trends  and 
non-randomness  (assuming  the  input  order  of  the  data  is  a meaningful  time 
sequence).  Common  statistics  such  as  Student's  t and  confidence  intervals  for 
the  mean  and  standard  deviation  are  also  included.  NBS  Technical  Note  756,  A 
User's  Guide  to  the  OMNITAB  Command  "STATISTICAL  ANALYSIS,"  by  H.  H.  Ku  [1973] 
provides  a complete  discussion  of  the  output  of  these  subroutines,  which  is 
the  same  output  as  that  provided  by  the  OMNITAB  II  Command  STATISTICAL  [Hogben 
et  al.  1971]  . 

Users  are  directed  to  §B  for  a brief  description  of  the  subroutines.  The 
declaration  and  CALL  statements  are  given  in  §C  and  the  subroutine  arguments 
are  defined  in  §D.  The  algorithms  used  and  output  produced  by  these 
subroutines  are  discussed  in  §E.  Sample  programs  and  their  output  are  shown 
in  §F. 


B .  Subroutine  Descriptions 

STAT  computes  and  prints  the  53  descriptive  statistics  described  in  §A. 

STATS  provides  the  same  analysis  as  STAT  but  allows  the  user  to  suppress 
the  printed  output  and  store  the  computed  statistics  for  further  use. 

STATW  and  STATWS  perform  a weighted  analysis  and  are  otherwise  identical 
to  STAT  and  STATS,  respectively. 


C .  Subroutine  Declaration  and  CALL  Statements 

NOTE:  Argument  definitions  and  sample  programs  are  given  in  §D  and  §F, 
respectively.  The  conventions  used  to  present  the  following  declaration  and 
CALL  statments  are  given  in  chapter  1,  §B  and  §D. 
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STAT:  Compute  and  print  53  statistics  describing  the  input  data 

<real>  Y(n) 

DOUBLE  PRECISION  DSTAK ( Idstak ) 

COMMON  /CSTAK/  DSTAK 


CALL  STAT  (Y,  N,  LDSTAK) 


STATS:  Compute  and  optionally  print  53  statistics  describing  input  data; 

return  statistics 

<real>  Y(n),  STS(53) 

DOUBLE  PRECISION  DSTAK {Idstak) 

COMMON  /CSTAK/  DSTAK 


CALL  STATS  (Y,  N,  LDSTAK,  STS,  NPRT ) 


STATW : Compute  and  print  53  statistics  describing  weighted  input  data 

<real>  Y(n),  WT (n) 

DOUBLE  PRECISION  DSTAK {Idstak) 

COMMON  /CSTAK/  DSTAK 


CALL  STATW  (Y,  WT,  N,  LDSTAK) 


STATWS:  Compute  and  optionally  print  53  statistics  describing  weighted  input 
data;  return  statistics 

<real>  Y (n  ) , WT(rc),  STS(53) 

DOUBLE  PRECISION  DSTAK (Idstak ) 

COMMON  /CSTAK/  DSTAK 


CALL  STATWS  (Y,  WT,  N,  LDSTAK,  STS,  NPRT) 


5-2 


D.  Dictionary  of  Subroutine  Arguments  and  COMMON  Variables 


NOTE: 


DSTAK 

IERR 

LDSTAK 

N 

NPRT 

STS 


— > indicates  that  the  argument  is  input  to  the  subroutine  and  that 
the  input  value  is  preserved; 

< — indicates  that  the  argument  is  returned  by  the  subroutine; 

<->  indicates  that  the  argument  is  input  to  the  subroutine  and  that 
the  input  value  is  overwritten  by  the  subroutine; 

— — indicates  that  the  argument  is  input  to  some  subroutines  and  is 
returned  by  others; 

***  indicates  that  the  argument  is  a subroutine  name; 

**•  indicates  that  the  variable  is  passed  via  COMMON. 

* * * The  DOUBLE  PRECISION  vector  in  COMMON  /CSTAK/  of  dimension  at 

least  LDSTAK.  DSTAK  provides  workspace  for  the  computations.  The 
first  LDSTAK  locations  of  DSTAK  will  be  overwritten  during 
subroutine  execution. 

* * * An  error  flag  returned  in  COMMON  /ERRCHK/.  [See  chapter  1,  § D . 5 . ] 

Note  that  using  (or  not  using)  the  error  flag  will  not  affect  the 
printed  error  messages  that  are  automatically  provided  even  when 
the  user  has  suppressed  the  normal  printed  output. 

IERR  = 0 indicates  that  no  errors  were  detected. 

IERR  = 1 indicates  that  improper  input  was  detected. 

-~>  The  length  of  the  DOUBLE  PRECISION  workspace  vector  DSTAK.  LDSTAK 
must  equal  or  exceed  (N/2)  + 7. 

— > The  number  of  observations. 

™ > The  argument  controlling  printed  output. 

If  NPRT  = 0 the  printed  output  is  suppressed. 

If  NPRT  £ 0 the  printed  output  is  provided. 

— > The  vector  of  dimension  at  least  53  that  contains  the  computed 
statistics.  The  contents  of  STS  are  listed  below,  along  with 
applicable  references;  the  number  in  parenthesis  is  the  location 
within  STS  that  the  given  statistic  is  stored.  In  the  formulas,  x 
denotes  the  ordered  observations  of  Y for  which  the  weight  is 
nonzero,  i.e. , xi  is  the  smallest  observation  of  Y with  a nonzero 
weight,  x^  is  the  largest  observation  of  Y with  a nonzero  weight, 
etc.  The  weight  associated  with  x-j_  is  denoted  w^.  Zero  weighted 

observations  are  not  included  in  the  analysis.  The  value  of 

expressions  enclosed  in  square  brackets,  e.g.,  [(k/2)  +1],  is  the 
largest  integer  less  than  or  equal  to  the  value  of  the 
expression. 

(1)  NUMBER  OF  OBSERVATIONS,  N 

(2)  NUMBER  OF  NONZERO  WEIGHTS,  k 
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(3) 


UNWEIGHTED  MEAN  [Dixon  and  Massey,  1957,  p.  14], 


^Snean  k I xi 
i = l 

(4)  WEIGHTED  MEAN  [Brownlee,  1965,  pp.  95-97], 


l_  (wi*xi) 

xwtdmean  ~ ili- — , . -.n 
k 

I wi 

i=l 

(5)  MEDIAN  [Dixon  and  Massey,  1957,  p.  70], 
xmedian  = x[(k+l)/2]  if  k is  odd 

xmedian  = °’5*(x[k/2]  + x[(k/2)  + 1])  if  k is  even 

(6)  MID-RANGE  [Dixon  and  Massey,  1957,  p.  71], 

xmid  = 0'5*(xi  + xk> 

(7)  25  PCT  UNWTD  TRIMMED  MEAN  [Crow  and  Siddiqui,  1967], 

k-[k/4] 

xtrim  = Ik~(2*  W^])]~l  l xi 

i=l+ [k/4] 

(8)  25  PCT  WTD  TRIMMED  MEAN, 

k-[k/4] 

l (wi'Xi) 

xwtdtritn  = ___ 

k-[k/4] 

l wi 

i=l+ [k/4] 

(9)  WEIGHTED  STANDARD  DEVIATION  [Snedecor  and  Cochran,  1967, 
P*  44] , 


s ( (k  1)  I wi*^xi  Xwtdmean^  ) 
i=l 

(10)  WTD  S«D.  OF  MEAN  [Brownlee,  1965,  p.  80], 


smean  = s ' ( I wi)W2 
i=l 
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(11)  RANGE  [Snedecor  and  Cochran,  1967,  p.  39], 


xrange  xk  X1 

(12)  MEAN  DEVIATION  [Duncan,  1965,  p.  50], 

k 

_ 1 V I i 

xmeandev  ~ x L I xi-xwtdmean I 
i=l 


(13)  VARIANCE  [Snedecor  and  Cochran,  1967,  p.  44], 

k 

s2  = (k-1)"1  l (Xi-Xvtdmean^2 

i = l 

(14)  COEF.  OF  VAR.  (PERCENT)  [Snedecor  and  Cochran,  1967,  p.  62], 
cvar  = | 100-s/xwtdmean| 

(15)  LOWER  CONFIDENCE  LIMIT,  MEAN  [Natrella,  1966,  pp.  2-2,  2-3], 
xmean  ~ t0.025*smean 

where  tQ  025  is  the  appropriate  t-statistic  with  (k-1) 
degrees  of  freedom 


(16)  UPPER  CONFIDENCE  LIMIT,  MEAN  [Natrella,  1966,  pp.  2-2,  2-3], 
xmean  + t0.025*smean 

where  tQ  Q25  is  the  appropriate  t-statistic  with  (k-1) 
degrees  of  freedom 


(17)  LOWER  CONFIDENCE  LIMIT,  S.D.  [Natrella,  1966,  p.  2-7], 
s*( (k-l)/x2oo975)1/2 

where  x20  975  is  t^ie  appropriate  chi-square  statistic  with 
(k-1)  degrees  of  freedom 

(18)  UPPER  CONFIDENCE  LIMIT,  S.D.  [Natrella,  1966,  p.  2-7], 

, . . 9 >1/2 

s*l (k-l)/xz0.025J 

where  x20  025  :*'s  t^ie  appropriate  chi-square  statistic  with 

(k-1)  degrees  of  freedom 

(19)  SLOPE  [Fisher,  1950,  p.  136], 


= ( k* (k2-l ) )-1 


k 

12  l i- 

i = l 


(x- 


^td 


mean  • 
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(20)  S.D.  OF  SLOPE, 

[(12,I  ^i-Xwtdmean)2)  ~ B2  * k- (k2 -1 )] 1 72 

SB  = Llli 

(k« (k2 -1 ) - (k-2)) 1/2 

(21)  SLOPE/S. D.  OF  SLOPE  = T, 

tQ  = B / sg  with  (k-2)  degrees  of  freedom 

(22)  PROB  EXCEEDING  ABS  VALUE  OF  OBS  T [Brownlee,  1965,  p.  344], 
Pr{t  < — | tQ  I and  t > + 1 1 q | } 

(23)  NO.  OF  RUNS  UP  AND  DOWN  [Brownlee,  1965,  p.  223],  r 

(24)  EXPECTED  NO.  OF  RUNS  [Bradley,  1965,  p.  279], 

E (r ) = (2k— 1 )/3 

(25)  S.D.  OF  NO.  OF  RUNS  [Bradley,  1965,  p.  279], 
rsd  = [ ( 1 6k—2  9 ) / 9 0 ] 

(26)  MEAN  SQ  SUCCESSIVE  DIFF  [Brownlee,  1965,  p.  222], 

k-1 

D = (k-l)~l  l (xi+1-Xi) 
i=l 

(27)  MEAN  SQ  SUCC  DIFF/VAR  [Brownlee,  1965,  p.  222], 

2 . 2 
D /s 

(28)  NO.  OF  + SIGNS, 

u = number  of  times  sign  of  (xd""xwtcjmean)  is  positive 

(29)  NO.  OF  - SIGNS, 

v = number  of  times  sign  of  (x^-x^j  ) is  negative 

(30)  NO.  OF  RUNS  [Brownlee,  1965,  p.  224], 

RUNS  = 1 + number  of  changes  in  sign  of  (x^'x^^  ) 

(31)  EXPECTED  NO.  OF  RUNS  [Brownlee,  1965,  p.  227], 

E(RUNS)  = 1 + (2«u«v)/k 
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(32)  S.D.  OF  RUNS  [Brownlee,  1965,  p.  230], 

RUNSgd  = ( [ (u+v)2 • (k-1 ) ] 1 • 2» u» v» ( 2» u» v - u - v))1/2 

(33)  DIFF . /S.D.  OF  RUNS  [Brownlee,  1965,  p.  230], 

[RUNS  - E(RUNS)]  / RUNSgd 

(34)  MINIMUM  [Natrella,  1966,  p.  19-1], 

xj  = smallest  value  with  nonzero  weight 

(35)  MAXIMUM  [Natrella,  1966,  p.  19-3], 

= largest  value  with  nonzero  weight 

(36)  BETA  ONE  [Snedecor  and  Cochran,  1967,  p.  86], 

lc 

61  = ( (k-D^s6)"1  ( l (xi~xwtdmean)3)2ck 

i = l 

(37)  BETA  TWO  [Snedecor  and  Cochran,  1967,  p.  87], 

lc 

62  = ((k-1)  *s  ) £ ^xi_xwtdmean^  *k 

i=l 

(38)  WTD  SUM.  OF  VALUES, 

k 

l wi*xi 

i=l 

(39)  WTD  SUM  OF  SQUARES, 

k 

I wrxi 

i=l 

(40)  WTD  SUM  OF  DEVS  SQUARED, 

k 2 
I wie (xi"xwtdmean^ 
i=l 

(41)  STUDENT'S  T [Brownlee,  1965,  p.  296], 

k 1/2 

t = ( l wd)  • / s with  (k-1)  degrees  of  freedom 

i = l 
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(42)  WTD  SUM  ABSOLUTE  VALUES, 


k 

l wi*  | | 

i=l 

(43)  WTD  AVE  ABSOLUTE  VALUES, 

I wi*  lxil 

i=l 


k 

I wi 

i=l 

(44-53)  FREQUENCY  DISTRIBUTION  [Freund  and  Williams,  1958,  p.  17]. 

WT  <--  The  vector  of  dimension  at  least  N that  contains  the  weights.  A 

zero  weight  excludes  the  corresponding  observation  from  the 
analysis.  If  the  weights  are  all  equal  to  1.0,  the  resulting 
analysis  is  equivalent  to  an  unweighted  analysis. 

Y -->  The  vector  of  dimension  at  least  N that  contains  the  observations. 

The  tests  for  trend  and  randomness  will  not  be  meaningful  unless 
the  sample  is  ordered  with  respect  to  time  or  some  other  relevant 
variable. 


E . Computational  Methods 


E . 1 , 


Formulas  for  the  computed  statistics  are  given  in  §D  under  argument  STS. 
The  code  for  the  statistical  analysis  subroutines  is  adapted  from  OMNITAB  II 
[Kogben,  et  al.  1971]. 


E .  2 . Computed  Results  and  Printed  Output 

The  output  consists  of  a one-page  display  of  the  53  statistics  listed  for 
argument  STS  in  §D.  The  argument,  NPRT,  controlling  the  printed  output  is 
discussed  in  §D. 

F . Example 

The  example  program  of  figure  F-la  uses  STAT  to  analyze  the  39 
measurements  of  the  velocity  of  light  shown  on  page  81  of  Mandel  [1964].  The 
output  from  STAT  is  shown  in  figure  F-lb. 


ci  n n ci 


MAIN  PROGRAM! 


PROGRAM  E X AM  PL 


DATAI 


C 

C DEMONSTRATE  STAT  USING  SINGLE  PRECISION  VERSION  OF  STARPAC 

C RUN  ON  CYBER  180/0*0. 

C 

C OUTPUT  UNIT  IS  6 (AUTOMATICALLY  EOUATED  TO  FILE  TAPE6  ON  CYBERS) 

C [SEE  CHAPTER  1#  SECTION  0.*] 

C 

C N.B.  DECLARATION  OF  Y MUST  BE  CHANGED  TO  DOUBLE  PRECISION  IF 

C DOUBLE  PRECISION  VERSION  OF  STARPAC  IS  USED. 

C 

REAL  Y ( 200 ) 

DOUBLE  PRECISION  DSTAM200I 
C 

COMMON  /CSTAK/  OSTAK 
C 

C SPECIFY  NECESSARY  DIMENSIONS 

C 

LDSTAK  • 200 

READ  NUMBER  OF  OBSERVATIONS 
OBSERVED  DATA 

READ  100*  N 

READ  101*  CYIII*  I-1»N) 

C 

C PRINT  TITLE  AND  CALL  STAT  TO  PERFORM  STATISTICAL  ANALYSIS 

C 

WRITE  (6#  102) 

CALL  STAT  (Y»  N*  LDSTAK) 

C 

STOP 

C 

C FORMAT  STATEMENTS 

C 

100  FORMAT  (15) 

101  FORMAT  (13F5.1) 

102  FORMAT  C'lRESULTS  OF  STARPAC  STATISTICAL  ANALYSIS'* 

* • SUBROUTINE  STAT') 

END 

30 

0.*  0.6  1.0  1.0  1.0  0.5  0.6  0.7  1.0  0.6  0.2  1.9  0.2 

0.*  0.0  -0.*  -0.3  0.0  -0.4  -0.3  0.1  -0.1  0.2  -0.5  0.3  -0.1 

0.2  -0.2  O.S  0.5  0.6  0.8  0.7  0.7  0.2  0.5  0.7  0.8  1.1 


Figure  F-la 


Example  program  using  STAT 
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CHAPTER  6 


ONE-WAY  ANALYSIS  OF  VARIANCE 


A.  Introduction 


STARPAC  contains  two  subroutines  for  one-way  analysis  of  variance.  The 
output  from  these  subroutines  includes  the  usual  analysis  of  variance  table 
plus  the  robust  Kruskal-Wallis  rank  test.  Comprehensive  summary  statistics 
are  also  given,  including  means,  standard  deviations,  standard  deviations  of 
the  mean  and  confidence  intervals  for  the  mean  of  each  group.  Within  group 
standard  deviations,  standard  deviations  of  the  mean  and  95-percent  confidence 
intervals  for  the  mean  are  given  assuming  fixed  effects  and  random  effects 
models  and  also  assuming  ungrouped  data.  The  output  also  includes  pair-wise 
multiple  comparisons  using  the  Newman-Keuls  and  Scheffe  techniques;  the 
Cochran's  C,  the  Bartlett-Box  F and  variance  ratio  tests  for  homogeneity  of 
variances;  and  the  random  effects  model  components  of  variance  estimate.  The 
analysis  performed  by  these  subroutines  is  the  same  as  that  performed  by  the 
OMNITAB  II  command  ONEWAY  [Hogben  et  al.  1971].  A reference  for  one-way 
analysis  of  variance  is  Brownlee  [1965],  chapter  10. 

Users  are  directed  to  §B  for  a brief  description  of  the  subroutines.  The 
declaration  and  CALL  statements  are  given  in  §C  and  the  subroutine  arguments 
are  defined  in  §D.  The  algorithms  used  and  output  produced  by  these 
subroutines  are  discussed  in  §E.  Sample  programs  and  their  output  are  shown 
in  §F . 


B . Subroutine  Descriptions 

Subroutine  A0V1  computes  and  prints  the  one-way  analysis  of  variance 
described  in  §A. 

Subroutine  A0V1S  provides  the  same  analysis  as  A0V1  but  allows  the  user 
to  suppress  the  printed  output  and  to  store  the  number  of  observations  in  each 
group,  the  group  means  and  the  group  standard  deviations. 

C . Subroutine  Declaration  and  CALL  Statements 

NOTE:  Argument  definitions  and  sample  programs  are  given  in  §D  and  §F, 

respectively.  The  conventions  used  to  present  the  following  declaration  and 
CALL  statments  are  given  in  chapter  1,  §B  and  §D. 
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A0V1: 


Compute  and  print  a one-way  analysis  of  variance  of  the  input  data 


REAL  Y(n) , TAG(rc) 

DOUBLE  PRECISION  DSTAK (Idstak) 
COMMON  / CSTAK/  DSTAK 


CALL  A0V1  (Y,  TAG,  N,  LDSTAK) 


AOV1S:  Compute  and  optionally  print  a one-way  analysis  of  variance  of  the 

input  data;  return  tag  value  of  each  group , number  of  observations  in 
each  groups  group  averages,  and  group  standard  deviations 

REAL  Y(n) , TAG(n),  GSTAT (igs tat,  4) 

DOUBLE  PRECISION  DSTAK( Idstak) 

COMMON  /CSTAK/  DSTAK 


CALL  AOV1S  (Y,  TAG,  N,  LDSTAK,  NPRT,  GSTAT,  IGSTAT,  NG) 


D.  Dictionary  of  Subroutine  Arguments  and  COMMON  Variables 


NOTE:  -->  indicates  that  the  argument  is  input  to  the  subroutine  and  that 

the  input  value  is  preserved; 

<—  indicates  that  the  argument  is  returned  by  the  subroutine; 

<->  indicates  that  the  argument  is  input  to  the  subroutine  and  that 
the  input  value  is  overwritten  by  the  subroutine; 

indicates  that  the  argument  is  input  to  some  subroutines  and  is 
returned  by  others; 

***  indicates  that  the  argument  is  a subroutine  name; 

*  *  * * indicates  that  the  variable  is  passed  via  COMMON. 

DSTAK  **•  The  DOUBLE  PRECISION  vector  in  COMMON  /CSTAK/  of  dimension  at 
least  LDSTAK.  DSTAK  provides  workspace  for  the  computations.  The 
first  LDSTAK  locations  of  DSTAK  will  be  overwritten  during 
subroutine  execution. 

GSTAT  <—  The  matrix  of  dimension  at  least  NG  by  four  whose  columns  contain, 
in  order,  the  tag  value  of  the  group,  number  of  observations  in 
the  group,  group  average  and  group  standard  deviation.  The  groups 
are  in  order  of  ascending  tag  values. 

I ERR  **•  An  error  flag  returned  in  COMMON  /ERRCHK/ . [See  chapter  1,  § D . 5 . ] 
Note  that  using  (or  not  using)  the  error  flag  will  not  affect  the 
printed  error  messages  that  are  automatically  provided  even  when 
the  user  has  suppressed  the  normal  printed  output. 

IERR  = 0 indicates  that  no  errors  were  detected. 

IERR  = 1 indicates  that  improper  input  was  detected. 
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IGSTAT  — > The  exact  value  of  the  first  dimension  of  the  matrix  GSTAT  as 
specified  in  the  calling  program. 


LDSTAK  -->  The  length  of  the  DOUBLE  PRECISION  workspace  vector  DSTAK.  LDSTAK 
must  equal  or  exceed  the  appropriate  value  given  below,  where  if 
the  single  precision  version  of  STARPAC  is  being  used  P =0.5, 
otherwise  P = 1.0  [see  chapter  1,  § B ] . 

For  AOV 1 : LDSTAK  > 22  + N + (8«NG+N)*P 

For  AOV 1 S : LDSTAK  ^ 22  + N + (4*NG+N).P 

N — > The  total  number  of  observations  (all  of  the  groups  combined). 


NG  <--  The  number  of  distinct  groups,  that  is,  the  number  of  different 

positive  tag  values. 

NPRT  — > The  parameter  controlling  printed  output. 

If  NPRT  = 0 the  printed  output  is  suppressed. 

If  NPRT  t 0 the  printed  output  is  provided. 

TAG  — > The  vector  of  dimension  at  least  N that  contains  the  tag  value  for 

each  observation.  The  tag  values  may  be  any  REAL  number.  Groups 
are  formed  from  observations  having  the  same  positive  tag  value. 
Observations  having  a zero  or  negative  tag  value  will  not  be 
included  in  the  analysis. 

Y — > The  vector  of  dimension  at  least  N that  contains  the  observed 

data.  The  order  of  the  observations  in  Y is  arbitrary  since 

groups  are  specified  by  the  values  in  the  corresponding  elements 
of  vector  TAG. 


E . Computational  Methods 
E . 1 Algorithms 

The  code  and  output  for  the  one-way  analysis  of  variance  subroutines  are 
adapted  from  OMNITAB  II  [Hogben  et  al.  1971].  The  computations  performed  are 
discussed  below. 


E . 2 Computed  Results  and  Printed  Output 

The  argument  controlling  the  printed  output,  NPRT,  is  discussed  in  §D. 

Each  of  the  five  sections  of  automatic  printing  is  described  below  under 
the  headings  which  appear  on  the  printed  page  as  shown  in  example  F-lb.  The 
discussion  is  taken  from  the  OMNITAB  II  User's  Reference  Manual  [Hogben  et 
al.  1971],  pages  122  to  124. 
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ANALYSIS  OF  VARIANCE.  The  traditional  analysis  of  variance  for  a one-way 
classification  is  printed.  This  shows  the  sources  of  variation,  the  degrees 
of  freedom,  the  sums  of  squares,  the  mean  squares,  the  F-ratio  for  testing  for 
differences  between  group  means  and  the  significance  level  of  the  F-ratio. 
The  usual  assumptions  of  normality,  independence  and  constant  variance  of 
measurement  errors  are  made.  A discussion  of  the  statistical  treatment  of  a 
one-way  classification  can  be  found  in  §10.2  of  Brownlee  [1965], 

If  the  significance  level  of  the  F ratio  (F  PROB . ) for 

F = (Between  Groups  Mean  Square)  / (Within  Groups  Mean  Square) 

is  less  than  0.10  and  the  number  of  groups  exceeds  two,  the  between  groups 
(means)  sum  of  squares  is  separated  into  two  components:  the  first  associated 
with  the  slope  (one  degree  of  freedom)  and  the  second  representing  deviations 
about  the  straight  line  regression  of  group  averages  on  group  number.  This 
information,  which  does  not  appear  in  a traditional  analysis  of  variance,  can 
be  used  to  examine  the  effect  of  time.  A discussion  of  some  of  the 
statistical  aspects  of  this  procedure  are  found  in  §11.12  of  Brownlee  [1965]. 

Following  the  above  mentioned  analysis  of  variance,  the  results  for  the 
Kruskal-Wallis  non-parame  t ri  c H-~test  for  testing  for  differences  between  group 
means  (averages)  are  printed.  The  value  of  H is  printed  along  with  its 
significance  level  (F  PROB.).  The  H-test  uses  the  ranks  of  the  measurements 
and  avoids  any  assumption  about  the  distribution  of  measurement  errors. 
Details  of  this  test  may  be  found  in  §7.7  of  Brownlee  [1965]. 


E STIMATES.  The  following  items  are  printed  for  each  group: 

(1)  group  number, 

(2)  number  of  observations  in  the  group, 

(3)  mean, 

(4)  within  standard  deviation, 

(5)  standard  deviation  of  the  mean, 

(6)  minimum  (i.e.,  smallest)  observation, 

(7)  maximum  (i.e.,  largest)  observation, 

(8)  the  sum  of  the  ranks  of  the  observations,  and 

(9)  a 95-percent  confidence  interval  for  the  mean. 

The  results  are  printed  with  the  group  numbers  (tags)  in  consecutive, 
increasing  order  regardless  of  the  order  in  which  the  numbers  were  entered. 

In  printing  the  means  and  standard  deviations  of  the  groups,  the 
characters  + and  - are  put  immediately  after  the  high  (largest)  and  low 
(smallest)  values.  If  two  or  more  values  are  tied  for  the  largest  value,  the 
character  + is  put  immediately  after  all  of  the  tied  values.  Ties  for  the 
smallest  values  are  handled  in  an  analogous  manner  using  the  character  -.  If 

the  number  of  observations  in  a group  equals  one,  ESTIMATE  NOT  AVAILABLE  is 
printed  under  WITHINS  S.D.  and  S.D.  OF  MEAN.  Also,  **********  TO  ********** 
appears  under  95PCT  CONF  INT  FOR  MEAN. 

The  total  number  of  observations,  mean,  minimum  observation  and  maximum 
observation  are  also  printed  for  the  whole  dataset  combined.  In  addition,  the 
within  standard  deviation,  standard  deviation  of  the  mean  and  95-percent 
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confidence  interval  for  the  mean  are  printed  for  three  different  models:  a 
fixed  effects  model  (Model  I),  a random  effects  model  (MODEL  II)  and  a model 
which  assumes  that  all  observations  are  from  a single  group.  The  confidence 
limits  are  formed  by  taking  the  grand  mean  plus  (and  minus)  the  product  of  the 
percentage  point  of  Student's  t distribution  and  the  standard  deviation  of  the 
mean.  Let  k be  the  number  of  groups  and  n be  the  total  number  of  observations 
with  postitive  tag.  Then,  the  standard  deviation  of  the  mean  is  the  square 
root  of  the  variance  of  the  mean  formed  as  follows: 


Model 

Variance 

Variance  of 
Mean 

Degrees  of 
Freedom 

I 

Vj  = Within  groups  mean  square 

Vx/n 

n-k 

II 

vn  * I (Yd)  - T)2/0-l) 

i=l 

vn/k 

t— i 

i 

Ungrouped 

Vu  = Total  mean  square 

Vn 

n-1 

PAIRWISE  MULTIPLE  COMPARISON  OF  MEANS.  This  section  only  appears  if  the 
significance  level  (value  of  F PROB.)  of  the  between  groups  F-ratio  is  less 
than  0.10.  The  Newman-Keuls-Hartley  procedure  is  not  performed  if  the  number 
of  measurements  with  positive  tag  is  less  than  four  plus  the  number  of 
groups. 

The  purpose  of  this  comparison  is  to  divide  the  groups  in  such  a way  that 
the  group  means  within  a division  are  not  significantly  different  at  the  0.05 
significance  level,  whereas  the  group  means  in  different  divisions  are 
significantly  different  at  the  0.05  level.  Two  different  procedures  are  used: 
the  Newman-Keuls-Hartley  method  and  the  Scheffe"  method.  The  two  methods  are 
similar  but  not  identical  and  frequently  give  slightly  different  results.  The 
Newman-Keuls-Hartley  method  is  described  in  §10.6  of  Snedecor  [1956]  and  §10.8 
of  Snedecor  and  Cochran  [1967].  The  Scheffe^  method  is  discussed  in  §10.3  of 
Brownlee  [1965]  . Groups  are  separated  by  a string  of  five  asterisks.  If  two 
divisions  have  no  group  means  in  common,  the  two  divisions  are  separated  by 
two  strings  of  five  asterisks. 

Both  the  Newman-Keuls-Hartley  method  and  the  Scheffe^  method  require 
percentage  points  of  the  studentized  range:  an  approximation  developed  by 
Mandel  is  used  to  compute  them.  Since  the  Newman-Keuls-Hartley  method  is 
designed  for  use  when  the  number  of  observations  in  each  group  is  the  same, 
the  number  of  observations  in  each  of  the  two  groups  is  approximated  by  m, 
where 

1/m  = (1/2)*(l/mi  + 1/m j ) 

and  m^  and  m^  are  the  actual  number  of  measurements  in  each  of  the  two 
g roups. 


TEST  FOR  HOMOGENEITY  OF  VARIANCES.  The  usual  analysis  of  variance  for  a 
one-way  classification  assumes  that  the  variances  of  all  groups  are  the  same. 
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This  section  of  output  provides  information  for  assessing  the  validity  of  this 
assumption.  Small  values  of  the  significance  level  P indicate  lack  of 
homogeneity  of  variance.  The  Cochran's  C statistic  printed  is  discussed  on 
page  180  of  Dixon  and  Massey  [1957]  and  in  more  detail  in  chapter  15  of 
Eisenhart  et  al.  [1947].  The  Bartlett-Box  F-test  is  a modification  of 
Bartlett's  test  which  uses  the  F-distribution  rather  than  the  chi-squared 
distribution  and  is  less  sensitive  to  non-normality.  It  is  discussed  on  pages 
179  and  180  of  Dixon  and  Massey  [1957],  A table  of  critical  values  of 
(maximum  variance) / (minimum  variance)  for  equal  sample  sizes  is  given  on  pages 
100  and  101  of  Owen  [1962]. 

If  either  P value  is  less  than  or  equal  to  0.10,  the  approximate  between 
mean  F-test  in  the  presence  of  heterogeneous  variance  and  its  significance 
level  P are  also  printed.  This  approximate  F-test  for  testing  for  differences 
between  means  is  described  on  pages  287-289  of  Snedecor  [1956] . This 
information  does  not  appear  in  figure  F-lb  because  both  P values  (significance 
levels)  exceed  0.10. 


MODEL  II  - COMPONENTS  OF  VARIANCE.  This  is  the  usual  analysis  of 
variance  estimate  for  the  between  component  in  a random  effects  model  (Model 
II).  For  a discussion  of  this  analysis,  see  §10.6  and  §10.7  of  Brownlee 
[1965]. 


The  example  program  of  figure  F-la  uses  A0V1  to  analyze  16  determinations 
of  the  gravitational  constant,  grouped  according  to  the  material  used  to  make 
the  measurements.  Figure  F-lb  shows  the  output  from  this  example.  A 
discussion  of  this  example  can  be  found  on  pages  314-316  of  Brownlee  [1965]. 


MAIN  PROGRAMI 


PROGRAM  EXANPL 


DATA  8 


C 

C DEMONSTRATE  AO VI  USING  SINGLE  PRECISION  VERSION  OP  STARPAC 

C RUN  ON  CYBER  180/BA0. 

C 

C OUTPUT  UNIT  IS  6 (AUTOMATICALLY  EOUATED  TO  FILE  T A P E 6 ON  CYRERS) 

C [SEE  CHAPTER  1#  SECTION  D.AI 

C 

C N.B.  DECLARATION  OF  Y AND  TAG  MUST  BE  CHANGED  TO  DOUBLE  PRECISION 

C IF  DOUBLE  PRECISION  VERSION  OF  STARPAC  IS  USED. 

C 

REAL  Y ( 2 0 ) > T AG ( 20 ) 

DOUBLE  PRECISION  DSTAM200) 

C 

COMMON  /CSTAK/  DSTAK 
C 

C SPECIFY  NECESSARY  DIMENSIONS 

C 

LDSTAK  ■ 200 
C 

C RE  AO  NUMBER  OF  OBSERVATIONS 

C OBSERVED  DATA 

C TAG  VALUES 

C 

READ  100,  N 

READ  101,  ( Y ( I ) » I«1,N) 

READ  101,  ( TAG ( I ) , I ■ 1 » N ) 

C 

C PRINT  TITLE  AND  CALL  A0V1  FOR  ANALYSIS  OF  VARIANCE 

C 

WRITE  (6,  102) 

CALL  A0V1  (Y,  TAG,  N,  LDSTAK) 

C 

STOP 

C 

C FORMAT  STATEMENTS 

C 

100  FORMAT  (15) 

101  FORMAT  (20F5.U 

102  FORMAT  ( '1RESULTS  OF  STARPAC  ONE-WAY  ANALYSIS  OF  VARIANCE', 

* • SUBROUTINE  AOVl'J 

ENO 


16 

83. 0  81.0 

1.0  1.0 


76.0  78.0 

1.0  1.0 


79.0  72.0 

1.0  1.0 


61. 0 61.0 

2.0  2.0 


67.0  67.0 

2.0  2.0 


6 A . 0 78.0 

2.0  3.0 


71.0  75.0 

3.0  3.0 


72. C 7 A . 0 

3.0  3.0 


Figure  F-la 


Example  program  using  AOV 1 
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CHAPTER  7 


CORRELATION  ANALYSIS 


A.  Introduction 

STARPAC  contains  two  subroutines  for  correlation  analysis  of  a multivari- 
ate random  sample.  The  analysis  provided  by  these  subroutines  consists  of 
seven  tables,  which,  when  used  together,  aid  the  user  in  using  correlation 
techniques  effectively  for  prediction  and  model  building.  The  analysis  is  the 
same  as  that  provided  by  the  OMNITAB  II  command  CORRELATION  [Hogben  et  al. 
1971],  For  further  information  on  correlation  techniques  users  should  consult 
Kendall  and  Stuart  [1973],  Brownlee  [1965]  and  Anderson  [1958]. 

Users  are  directed  to  §B  for  a brief  description  of  the  subroutines.  The 
declaration  and  CALL  statements  are  given  in  §C  and  the  subroutine  arguments 
are  defined  in  §D.  The  algorithms  used  and  output  produced  by  these 
subroutines  are  discussed  in  §E.  Sample  programs  and  their  output  are  shown 
in  §F . 


B .  Subroutine  Descriptions 

Subroutine  CORR  computes  and  prints  1)  the  simple  correlation  matrix  and 
2)  the  significance  levels  of  the  simple  correlation  coefficients;  3)  the 
partial  correlation  coefficients  and  4)  their  significance  levels;  5)  the 
Spearman  rank  correlation  coefficients;  6)  a test  for  a quadratic  relationship 
among  the  variables;  and  7)  95-percent  and  99-percent  confidence  intervals  for 
the  simple  correlation  coefficients. 

Subroutine  CORRS  provides  the  same  analysis  as  CORR  but  returns  the 
variance-covariance  matrix  used  to  compute  the  correlation  coefficients.  The 
user  can  also  optionally  suppress  the  printed  output. 


C .  Subroutine  Declaration  and  CALL  Statements 

NOTE;  Argument  definitions  and  sample  programs  are  given  in  §D  and  §F, 
respectively.  The  conventions  used  to  present  the  following  declaration  and 
CALL  statments  are  given  in  chapter  1,  §B  and  §D. 

CORR:  Compute  and  print  a correlation  analysis  of  a multivariate  random 

sample 

<real>  YM (n,m) 

DOUBLE  PRECISION  DSTAK (Idstak) 

COMMON  / CSTAK/  DSTAK 

CALL  CORR  (YM,  N,  M,  IYM , LDSTAK ) 
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CORRS:  Compute  and  optionally  print  a correlation  analysis  of  a multivariate 

random  sample;  return  variance- oovarianee  matrix 

<real>  YM(n,  m)  > VC 

DOUBLE  PRECISION  DST AK (l dstak ) 

COMMON  /CSTAK/  DSTAK 

t 

CALL  CORRS  (YM,  N,  M,  IYM,  LDSTAK,  NPRT,  VCV , IVCV) 


D.  Dictionary  of  Subroutine  Arguments  and  COMMON  Variables 

NOTE:  — > indicates  that  the  argument  is  input  to  the  subroutine  and  that 

the  input  value  is  preserved; 

<--  indicates  that  the  argument  is  returned  by  the  subroutine; 

<->  indicates  that  the  argument  is  input  to  the  subroutine  and  that 
the  input  value  is  overwritten  by  the  subroutine; 

— - indicates  that  the  argument  is  input  to  some  subroutines  and  is 
returned  by  others; 

***  indicates  that  the  argument  is  a subroutine  name; 

* * • indicates  that  the  variable  is  passed  via  COMMON. 


DSTAK  The  DOUBLE  PRECISION  vector  in  COMMON  /CSTAK/  of  dimension  at 

least  LDSTAK.  DSTAK  provides  workspace  for  the  computations.  The 
first  LDSTAK  locations  of  DSTAK  will  be  overwritten  during 
subroutine  execution. 

IERR  ' * * An  error  flag  returned  in  COMMON  /ERRCHK/.  [See  chapter  1,  §D.5.] 
Note  that  using  (or  not  using)  the  error  flag  will  not  affect  the 
printed  error  messages  that  are  automatically  provided  even  when 
the  user  has  suppressed  the  normal  printed  output. 

IERR  = 0 indicates  that  no  errors  were  detected. 

IERR  = 1 indicates  that  improper  input  was  detected. 

IVCV  - — > The  exact  value  of  the  first  dimension  of  the  matrix  VCV  as 

specified  in  the  calling  program. 

IYM  — > The  exact  value  of  the  first  dimension  of  the  matrix  YM  as 

specified  in  the  calling  program. 

LDSTAK  — > The  length  of  the  double  precision  workspace  vector  DSTAK.  LDSTAK 
must  equal  or  exceed  the  appropriate  value  given  below,  where  if 

the  single  precision  version  of  STARPAC  is  being  used  P = 0.5, 

otherwise  P = 1.0.  [See  chapter  1,  §B.] 

— continued  — 
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For  CORR: 


LDSTAK  > (47+max(N,M)) /2  + (max(N,M)+N« (M+3)+M+7« M2 ) «P 
For  CORRS: 

LDSTAK  > (47+IO«max(N,M)) /2  + 10 • (max(N,M)+N» (M+3)+M+6*  M2 ) • P 

where  10  = 0 if  NPRT  = 0 and  10  = 1 if  NPRT  t 0 

M — > The  number  of  variables  measured  for  each  observation,  that  is, 

the  number  of  columns  of  data  in  YM. 

N -->  The  number  of  observations,  that  is,  the  number  of  rows  of  data  in 

YM. 

NPRT  -->  The  argument  controlling  printed  output. 

If  NPRT  = 0 the  printed  output  is  suppressed. 

If  NPRT  t 0 the  printed  output  is  provided. 

VCV  <—  The  matrix  of  dimension  at  least  M by  M that  contains  the 

variance-covariance  matrix, 

N 

VCV  ( j , k)  = (N-l)"1  l (YM(i,j)  - Y0(YM(i,k)  - Yfc) 

i=l 

N _ N 

where  Y-  = N”1  . J YM(i,j)  and  Yk  = N"1  . J YM(i,k). 

i=l  i=l 

YM  -->  The  matrix  of  dimension  at  least  N by  M that  contains  the  observed 

multivariate  data.  The  element  in  the  i1-*1  row  and  column  is 

the  ic^  observation  on  the  variable. 


E . Computational  Methods 
E . 1 Algorithms 


Formulas  for  the  computed  tables  are  given  in  §E.2.  The  code  and  output 
for  the  correlation  analysis  subroutines  are  adapted  from  OMNITAB  II  [Hogben 
et  al.  1971]  . 


E . 2 Computed  Results  and  Printed  Output 

The  argument  controlling  the  printed  output,  NPRT,  is  discussed  in  §D. 
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STARPAC  correlation  analysis  subroutines  compute  and  print  a seven-part 
correlation  analysis.  The  output  for  each  part  is  discussed  individually 
below;  the  text  for  this  discussion  is  taken  from  the  OMNITAB  II  User’s 
Reference  Manual  [Hogben  et  al.  1971], 


The  Simple  Correlation  Coefficient  Matrix.  The  (j,k)t^1  entry  of  this 
matrix  is  the  simple  (product  moment)  correlation  coefficient,  rjk>  between 
the  data  in  columns  j and  k defined  by 

rik  = VCV(.j,k)  t 
(VCV(j,j).VCV(k,k))l/2 

Note  that  when  more  than  two  variables  are  under  study,  the  simple  correlation 
coefficient  can  be  seriously  distorted  by  the  effect  of  other  variables.  The 
partial  correlation  coefficient  (see  below)  can  be  used  to  identify  such 
distortion. 


The  Significance  Levels  of  the  Simple  Correlation  Coefficients.  The 
(jjk)"^  entry  of  this  table  is  the  significance  level,  Sr ( j , k)  of  the 
corresponding  partial  correlation  coefficient,  rjk, 

Sr(j,k)  = probability  of  exceeding  Fq(1,N-2) 
where  Fq  is  an  F-statistic  with  1 and  N-2  degrees  of  freedom, 

(N-2)rik2 

F0(  1 ,N-2)  = — 

( l“r jk2 ) 

If  the  “true"  correlation  coefficient  is  equal  to  zero,  then  Sr(j,k)  is  the 
probability  that  in  a random  sample  (of  the  same  size)  the  absolute  value  of  a 
sample  correlation  coefficient  will  exceed  the  absolute  value  of  the  observed 
correlation  coefficient,  rj^.. 

The  Partial  Correlation  Coefficients.  The  partial  correlation 
coefficient,  Pjk>  between  the  data  in  columns  j and  k,  j*k,  with  the  remaining 
variables  fixed,  i.e.,  held  constant,  is  given  by 

Pjk  ~ “cjk^c  j j * ckk^ 

where  Cjk  denotes  the  (j,k)t'1  element  of  the  inverse  of  the  simple  correlation 
matrix.  Because  the  partial  correlation  coefficient  measures  the  correlation 
between  two  variables  after  eliminating  the  effect  of  the  remaining  variables, 
it  may  avoid  the  distortion  suffered  by  the  simple  correlation  coefficient 
when  more  than  two  variables  are  under  study.  The  user  should  therefore 
compare  the  simple  correlation  coefficients  with  the  partial  correlation 
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coefficients.  Any  "large"  discrepancy  indicates  that  one  or  more  of  the 
remaining  variables  is  having  an  important  effect  on  the  relationship.  [See 
Kendall  and  Stuart,  1961,  §27.5,  page  318.] 

The  Significance  Levels  of  the  Partial  Correlation  Coefficients.  The 
entry  of  this  table  is  the  significance  level,  Sp( j , k)  of  the 
corresponding  partial  correlation  coefficient,  pjk, 

Sp(j,k)  = probability  of  exceeding  Fq(1,N-M) 

where  Fq  is  an  F-statistic  with  1 and  N-M  degrees  of  freedom, 

(N-M)p jk2 
Fq(1,N-M)  = • 

(1-Pjk2) 

If  the  "true"  partial  correlation  coefficient  is  equal  to  zero,  then  Sp(j,k) 
is  the  probability  that  in  a random  sample  (of  the  same  size)  the  absolute 
value  of  a partial  correlation  coefficient  will  exceed  the  absolute  value  of 
the  observed  partial  correlation  coefficient,  Pjk* 


Spearman  Rank  Correlation  Coefficient.  The  rank  correlation  coefficient 
does  not  require  the  assumption  that  the  data  have  a bivariate  normal 
distribution.  The  Spearman  rank  correlation  coefficient,  Sjk,  for  the  data  in 
columns  j and  k is  computed  from 


where 


/(A  - 2Tj ) (A  - 2Tk) 


N 

Djk2  = l [ r ank ( YM ( i , j ) ) - rank(  YM(i  ,k))  ]2  , 
i = l 

A = (N— l)(N)(N+l)/6, 

Tj  > (l/12)g(tJ-l)(tj)(tj+l)), 

j 

Tk  = (l/12)K(tk-D(tk)(tk+l», 

k 


tj  - number  of  ties  in  a set  of  tied  values  in  column  j of  YM , and 
tk  = number  of  ties  in  a set  of  tied  values  in  column  k of  YM. 
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If  there  are  no 


The  quantities  Tj  and  adjust  for  ties  in  the  ranks, 
ties,  Tj  and  equal  zero  and 

Sjk  - 1 ~ (Djk  / A). 

A comparison  should  be  made  between  the  rank  correlation  coefficients  and  the 
corresponding  simple  and  partial  correlation  coefficients.  Again,  a "large" 
discrepancy  between  two  comparable  coefficients  is  an  indicator  of  some 
abnormality  in  the  data.  See  Kendall  [1948]  for  further  details. 


Significance  Level  of  Quadratic  Fit  over  Linear  Fit.  Underlying  the  use 
of  a correlation  coefficient  is  the  assumption  that  the  two  variables  are 
linearly  related.  The  results  in  this  part  are  useful  in  assessing  the 
validity  of  this  assumption  of  linearity.  The  variables  are  all  assumed  to  be 
normally  distributed.  The  numbers  printed  are  the  significance  levels  for  a 
F-test  of  the  hypothesis  that  the  quadratic  term  in  a quadratic  model  is  zero. 
The  F-statistic  used  is 

Fq(1,N-3)  = RSS(linear  model)  - RSS(quadratic  model) 

RSS(quadratic  model) / (N-3) 

with  1 and  (N-3)  degrees  of  freedom,  where  RSS  is  the  residual  sum  of  squares 
function.  The  values  of  1 and  (N-3)  are  printed  in  the  heading.  The 
significance  level,  Sq,  is  then  computed  as 

Sq  = Pr(F  > Fq). 

Small  values  of  the  significance  level  (less  than  0.05,  for  example)  indicate 
lack  of  linearity.  The  test  results  differ  depending  upon  which  variable  of  a 
pair  is  considered  the  dependent  variable  and  which  one  is  considered  the 
independent  (or  predictor)  variable.  Hence,  the  entire  table  is  printed, 
rather  than  just  the  lower  triangle.  The  diagonal  entries  are  always  equal  to 
one  and  have  no  particular  relevance.  Tests  of  hypotheses  in  linear 
regression  are  discussed  in  §13.8  of  Brownlee  [1965]. 


Confidence  Intervals  For  Simple  Correlation  Coefficients.  Both  95-percent 
and  99-percent  confidence  intervals  for  the  simple  correlation  coefficients 
are  printed  in  this  two-way  table.  There  are  two  entries  in  each  cell  of  the 
table.  The  values  0.95  and  0.99  are  printed  along  the  upper  left  to  lower 
right  diagonal.  The  95-percent  confidence  limits  are  printed  below  the 
diagonal  and  the  99-percent  confidence  limits  are  printed  above  the  diagonal. 
The  number  in  the  lower  left  of  each  cell  is  the  lower  confidence  limit  and 
the  number  in  the  upper  right  is  the  upper  confidence  limit. 

The  confidence  intervals  are  based  on  a normal  approximation.  [See 
Morrison,  1967,  chapter  3,  page  101.]  They  are  computed  as  follows: 

Lower  confidence  limit:  tanh[z-u  //N-3] 

Upper  confidence  limit:  tanh [z+u//N-3] 
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where 


and 


tanh  1 (r 

0.50  loge[ ( l+rjk)/(l-rjk) ] 


u 


1.96 


I 

2.58 


for  95-percent 
for  99-percent 


confidence 

confidence 


interval 

interval. 


F . Example 


The 
data  are 
study  to 
relative 
4) . The 


sample  program  shown  in  figure  F-la  illustrates  the  use  of  CORR.  The 
taken  from  Draper  and  Smith  [1968],  page  216.  The  data  are  part  of  a 
determine  the  effect  of  relative  urbanization,  educational  level,  and 
income  (columns  1,  2,  and  3,  respectively)  on  product  usage  (column 
output  from  CORR  is  shown  in  figures  F-lb  and  F-lc. 
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MAIN  PROGRANI 


PR06RAH  EXAMPl 


C 

C DEMONSTRATE  CORR  USING  SINGLE  PRECISION  VERSION  OP  STARPAC 

C RUN  ON  CYBER  180/840. 

C 

C OUTPUT  UNIT  IS  6 (AUTOMATICALLY  EQUATED  TO  PILE  TAPE6  ON  CYBERS) 

C ESEE  CHAPTER  1#  SECTION  D.43 

C 

C N.Be  DECLARATION  OP  YM  MUST  BE  CHANGED  TO  DOUBLE  PRECISION 

C IP  DOUBLE  PRECISION  VERSION  OF  STARPAC  IS  USED, 

C 

REAL  YN ( 20»  6 ) 

DOUBLE  PRECISION  DSTAM200S 
C 

COMMON  /CSTAK / DSTAK 
C 

C SPECIFY  NECESSARY  DIMENSIONS 

C 

LDSTAK  • 206 
I YM  = 20 
C 

C READ  NUMBER  OP  OBSERVATIONS  AND  NUMBER  OF  VARIABLES 
C OBSERVED  NULTIVARIATi  DATA 

C 

READ  160s  Ns  M 

READ  101#  ( (YH(Z#J)»  J«1#HI»  I«1#NJ 
C 

C PRINT  TITLE  AND  CALL  CORR  TO  PERFORM  CORRELATION  ANALYSIS 

C 

NR  I Ti ( 6# 162 ) 

CALL  CORR  < YM#  N#  H#  1 YM#  LOST AK I 
STOP 
C 

C FORMAT  STATEMENTS 

C 

100  FORMAT  (215) 

101  FORMAT  (AFfe.li 

102  FORMAT  (URESULTS  OF  STARPAC*# 

* » CORRELATION  ANALYSIS  SUBROUTINE  CORR*) 

END 

D AT  A l 9 A 
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30©1 
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10©8 

8.5 

174.6 

39.1 
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24.3 

163.7 

40©  1 

1 0 © 0 

18©fe 

174.5 

45  ©9 

12.0 

20.4 

IBS  .7 

Figure  F-la 


Example  program  using  CORR 
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Example  of  CORR  output 
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Example  of  CORR  output  (continued) 
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CHAPTER  8 


LINEAR  LEAST  SQUARES 


A.  Introduction 

STARPAC  contains  eight  subroutines  for  linear  least  squares  analysis. 
For  four  of  these,  the  user  specifies  the  model  by  supplying  the  design  matrix 
(the  matrix  whose  columns  are  the  independent  variables  plus  a column  of  ones 
if  a constant  term  is  being  estimated).  The  other  four  perform  the  same 
analysis  for  the  special  case  of  a polynomial  model,  where  the  need  for  the 
user  to  explicitly  create  the  design  matrix  is  eliminated. 

Each  of  the  subroutines  described  in  this  chapter  assumes  that  the 
observations  of  the  dependent  variable,  y^,  which  are  measured  with  error,  are 
modeled  by 

NPAR 

Yi  = [ I 6(j)*xi(j)]  + for  i = 1,  ...,  N, 

j = l 

where 

N is  the  number  of  observations; 

NPAR  is  the  number  of  parameters; 

x-^(j)  is  the  j1-^1  element  of  the  ic^  row  of  the  design  matrix  (for  the 
user-specified  model,  x^(j)  = XM(i,j)  for  i = 1,  ...,  N and  j = 1 , 
NPAR,  while  for  the  polynomial  model,  x.j_(j)  = X(i)d“l  for  i = 1, 

. . « , N and  j — 1,  NPAR^ ; 

8 is  the  vector  of  the  NPAR  unknown  parameters  (coefficients);  and 

ei  is  the  random  error  in  the  ith  observation. 

A 

The  least  squares  solution,  B,  is  that  which  minimizes  (with  respect  to  B)  the 
residual  sum  of  squares  function 

N 

RSS(B)  = l [e12-wti] 
i = l 

N - NPAR 

= l [(Yi  " [ l 3(j )*xi(j ) ])2 •wti] 

i=l  j=l 

where  carat  (A ) denotes  the  estimated  quantity,  and 

wtt  is  the  weight  assigned  to  the  ith  observation  (wt-L  = 1.0  in  the 

"unweighted"  case).  Appendix  B discusses  several  common  applications 
for  weighted  least  squares. 
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Users  are  directed  to  §B  for  a brief  description  of  the  subroutines.  The 
declaration  and  CALL  statements  are  given  in  §C  and  the  subroutine  arguments 
are  defined  in  §D.  The  algorithms  used  and  output  produced  by  these 
subroutines  are  discussed  in  §E.  Sample  programs  and  their  output  are  shown 
in  §F . 


B . Subroutine  Descriptions 

The  linear  least  squares  estimation  subroutines  permit  both  weighted  and 
unweighted  analysis.  The  user  has  two  levels  of  control  over  the  computations 
and  printed  output. 

• In  level  one,  a four-part  printed  report  is  automatically  provided 
and  the  residuals  are  returned  to  the  user  via  the  subroutine 
argument  list. 

• Level  two  also  returns  the  residuals.  It.  allows  the  user  to  specify 
the  amount  of  printed  output,  and,  in  addition,  returns  the 
following  estimated  values  via  the  argument  list: 

- the  estimated  parameters; 

- the  residual  standard  deviation; 

- the  predicted  values; 

- the  standard  deviations  of  the  predicted  values; 

- the  standardized  residuals;  and 

- the  variance-covariance  matrix  of  the  estimated  parameters. 

The  simplest  of  the  linear  least  squares  subroutines  are  LLS  for  the 
user-specified  model  and  LLSP  for  the  polynomial  model.  They  perform 
unweighted  analyses,  provide  a four-part  printed  report  and  return  the 
residuals  via  the  argument  list  (level  one  control).  The  other  six 
subroutines  provide  greater  flexibility  by  adding  the  weighting  and/or  level 
two  control  features.  These  features  are  each  indicated  by  a different  suffix 
letter  on  the  subroutine  name  (e.g.,  LLSS_  and  LLSPWS ) . 

• Suffix  W indicates  user-supplied  weights. 

• Suffix  S indicates  level  two  control  of  the  computations  and  output. 


C.  Subroutine  Declaration  and  CALL  Statements 


NOTE:  Argument  definitions  and  sample  programs  are  given  in  §D  and  §F , 
respectively.  The  conventions  used  to  present  the  following  declaration  and 
CALL  statements  are  given  in  chapter  1,  §B  and  §D. 
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LLS: 


Compute  and  print  a four-part  unweighted  linear  least  squares 
analysis  with  user-specified  model  (design  matrix);  return  residuals 


<real>  Y (n ) , XM (n,npar),  RES(n) 
DOUBLE  PRECISION  DSTAK (Idstak) 
COMMON  / CSTAK/  DSTAK 


CALL  LLS  (Y,  XM,  N,  IXM,  NPAR,  RES,  LDSTAK) 


LLSS:  Compute  and  optionally  print  a four-part  unweighted  linear  least 

squares  analysis  with  user- specified  model  (design  matrix);  return 
residuals,  parameter  estimates,  residual  standard  deviation,  predicted 
values,  standard  deviations  of  the  predicted  values,  standardized 
residuals,  and  variance-covariance  matrix  of  parameters 

<real>  Y (n  ) , XM (n  ynpar) , RES(n) 

<real>  PAR( npar),  PV(rc),  SDPV(n),  SDRES(n),  VCV( npar, npar) 

DOUBLE  PRECISION  DSTAK (Idstak) 

COMMON  /CSTAK/  DSTAK 


CALL  LLSS  (Y,  XM,  N,  IXM,  NPAR,  RES,  LDSTAK, 

1 NPRT,  PAR,  RSD,  PV,  SDPV,  SDRES , VCV , IVCV) 


LLSW:  Compute  and  print  a four-part  weighted  linear  least  squares  analysis 

with  user- specified  model  (design  matrix) ; return  residuals 

<real>  Y(n),  XM (n  ,npar) , RES(n) 

<real>  WT(rc) 

DOUBLE  PRECISION  DSTAK  (Idstak.) 

COMMON  /CSTAK/  DSTAK 


CALL  LLSW  (Y,  WT,  XM,  N,  IXM,  NPAR,  RES,  LDSTAK) 
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LLSWS:  Compute  and  optionally  print  a four-part  weighted  linear  least 

squares  analysis  with  user-speaified  model  (design  matrix) ; return 
residuals , parameter  estimates , residual  standard  deviation , predicted 
values , standard  deviations  of  the  predicted  values,  standardized 
residuals,  and  variance- covariance  matrix  of  parameters 

<real>  Y (n  ) , XM  (n,npar),  RES  (n) 

<real>  WT(n),  PAR  (npar),  PV(n),  SDPV(n),  SDRES(n),  VCV  (npar  ,npar ) 
DOUBLE  PRECISION  DSTAK (Idstak) 

COMMON  /CSTAK/  DSTAK 


CALL  LLSWS  (Y,  WT,  XM,  N,  IXM,  NPAR,  RES,  LDSTAK, 
1 NPRT,  PAR,  RSD,  PV,  SDPV,  SDRES , VCV,  IVCV) 


LLSP:  Compute  and  print  a four-part  unweighted  linear  least  squares 

analysis  with  polynomial  model  (design  matrix) ; return  residuals 

<real>  Y(n),  X(n),  RES(n) 

DOUBLE  PRECISION  DSTAK (Idstak) 

COMMON  /CSTAK/  DSTAK 


CALL  LLSP  (Y,  X,  N,  NDEG,  RES,  LDSTAK) 


LISPS:  Compute  and  optionally  print  a four-part  unweighted  linear  least 

squares  analysis  with  polynomial  model  (design  matrix);  return 
residuals,  parameter  estimates , residual  standard  deviation,  predicted 
values,  standard  deviations  of  the  predicted  values,  standardized 
residuals,  and  variance-covariance  matrix  of  parameters 

<real>  Y(n),  X(n),  RES(n) 

<real>  PAR  (npar),  PV(n),  SDPV(n),  SDRES  (n),  VCV  (npar , npar ) 

DOUBLE  PRECISION  DSTAK (Idstak) 

COMMON  /CSTAK/  DSTAK 


CALL  LLSPS  (Y,  X,  N,  NDEG,  RES,  LDSTAK, 

1 NPRT,  LPAR,  PAR,  NPAR,  RSD,  PV,  SDPV,  SDRES,  VCV,  IVCV) 
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LLSPW : Compute  and  print  a four-part  weighted  linear  least  squares  analysis 

with  polynomial  model  (design  matrix) ; return  residuals 

<real>  Y(n),  X(n),  RES(rc) 

<real>  WT(n) 

DOUBLE  PRECISION  DSTAK (Idstak) 

COMMON  / CSTAK/  DSTAK 


CALL  LLSPW  (Y,  WT,  X,  N,  NDEG,  RES,  LDSTAK) 


LLSPWS:  Compute  and  optionally  print  a four-part  weighted  linear  least 
squares  analysis  with  polynomial  model  (design  matrix);  return 
residuals , parameter  estimates , residual  standard  deviation , predicted 
values , standard  deviations  of  the  predicted  valuess  standardized 
residuals,  and  variance- covariance  matrix  of  parameters 

<real>  Y (n  ) , X(n),  RES(n) 

<real>  WT(n),  PAR  (npar),  PV(n),  SDPV(n),  SDRES(n),  VC  V (npar, npar) 
DOUBLE  PRECISION  DSTAK (Idstak) 

COMMON  /CSTAK/  DSTAK 


CALL  LLSPWS  (Y,  WT,  X,  N,  NDEG,  RES,  LDSTAK, 

1 NPRT,  LPAR,  PAR,  NPAR,  RSD,  PV,  SDPV,  SDRES , VCV , IVCV) 


D.  Dictionary  of  Subroutine  Arguments  and  COMMON  Variables 

NOTE:  — > indicates  that  the  argument  is  input  to  the  subroutine  and  that 

the  input  value  is  preserved; 

<--  indicates  that  the  argument  is  returned  by  the  subroutine; 

<->  indicates  that  the  argument  is  input  to  the  subroutine  and  that 
the  input  value  is  overwritten  by  the  subroutine; 

indicates  that  the  argument  is  input  to  some  subroutines  and  is 
returned  by  others; 

***  indicates  that  the  argument  is  a subroutine  name; 

•  *  * * indicates  that  the  variable  is  passed  via  COMMON. 

DSTAK  ***  The  DOUBLE  PRECISION  vector  in  COMMON  /CSTAK/  of  dimension  at 
least  LDSTAK.  DSTAK  provides  workspace  for  the  computations.  The 
first  LDSTAK  locations  of  DSTAK  will  be  overwritten  during 
subroutine  execution. 
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IERR 


IVCV 

IXM 

LDSTAK 

LPAR 

N 

NDEG 

NPAR 


**  An  error  flag  returned  in  COMMON  /ERRCHK/.  [See  chapter  1,  § D . 5 . ] 
Note  that  using  (or  not  using)  the  error  flag  will  not  affect  the 
printed  error  messages  that  are  automatically  provided  even  when 
the  user  has  suppressed  the  normal  printed  output. 

IERR  = 0 indicates  that  no  errors  were  detected  and  that  the 
least  squares  solution  was  found. 

IERR  = 1 indicates  that  improper  input  was  detected. 

IERR  = 2 indicates  that  the  model  is  computationally  singular, 
which  may  mean  the  model  has  too  many  parameters.  The 
user  should  examine  the  model  and  data  to  determine  and 
remove  the  cause  of  the  singularity. 

IERR  = 3 indicates  that  at  least  one  of  the  standardized  residuals 
could  not  be  computed  because  its  standard  deviation  was 
zero.  The  validity  of  the  variance-covariance  matrix  is 
questionable. 

->  The  exact  value  of  the  first  dimension  of  the  matrix  VCV  as 

specified  in  the  calling  program. 

— > The  exact  value  of  the  first  dimension  of  the  matrix  XM  as 

specified  in  the  calling  program. 

— > The  length  of  the  DOUBLE  PRECISION  workspace  vector  DSTAK.  LDSTAK 

must  equal  or  exceed  the  value  given  below,  where  if  the  single 

precision  version  of  STARPAC  is  being  used  P = 0.5,  otherwise 
P = 1.0.  [See  chapter  1,  §B.] 

LDSTAK  > 28  + [ 6®  N+l  + 5®  NPAR+NPAR*  N+2«  NPAR2  ]«P 

->  The  actual  length  of  the  vector  PAR  as  specified  in  the  calling 
program. 

— > The  number  of  observations. 

->  The  degree  of  the  polynomial  model.  The  number  of  estimated 
parameters  is  NPAR  = NDEG  + 1. 

— The  number  of  parameters  to  be  estimated.  NPAR  is  input  to  the 
subroutines  with  a user-specified  model;  for  the  subroutines  with 
a polynomial  model,  NPAR  = NDEG  + 1 is  returned. 
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NPRT  — > The  argument  controlling  printed  output.  NPRT  is  a four-digit 

integer,  where  the  value  of  the  I1-'1  digit  (counting  from  left  to 
right)  controls  the  Itla  section  of  the  output. 

If  the  I1-^1  digit  = 0,  the  output  from  the  I1"*1  section  is 

suppressed ; 

= 1,  the  brief  form  of  the  section  is  given; 

> 2,  the  full  form  of  the  I*-^1  section  is  given. 

The  default  value  for  NPRT  is  1112.  If  the  user-supplied  value  of 
NPRT  is  less  than  zero  or  NPRT  is  not  an  argument  in  the 
subroutine  CALL  statement  the  default  value  will  be  used. 

A full  discussion  of  the  printed  output  is  given  in  §E.2  and  is 
summarized  as  follows. 

Section  1 provides  information  for  each  observation  based  on  the 
solution.  Brief  output  includes  information  for  the 
first  40  observations,  while  full  output  provides  the 
information  for  all  of  the  data. 

Section  2 is  a set  of  four  residual  plots.  Brief  output  and  full 
output  are  the  same  for  this  section. 

Section  3 is  an  analysis  of  variance.  Brief  output  and  full 
output  are  the  same  for  this  section. 

Section  4 is  the  final  summary  of  the  estimated  parameters.  Brief 
output  does  not  include  printing  the  variance-covariance 
matrix  while  full  output  does. 

PAR  <--  The  vector  of  dimension  at  least  NPAR  that  contains  the  estimated 
parameter  values. 

PV  <—  The  vector  of  dimension  at  least  N that  contains  the  predicted 

values  of  the  dependent  variable, 


RES 


NPAR  - 

PV(i)  = l 8(j). 

j = l 

<—  The  vector  of  dime 


the  solution, 

NPAR 

RES(i)  = y±  - 

I 

j = l 

= Yi  “ 

Yi  = 

i( j ) = y±  for  i = 1 , . . . , 
sion  at  least  N that  cont 

A 

8 ( j ) xi(j) 

Ak 

for  i = 1 , . . . , N. 


N. 

ins  the  residuals  at 
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RSD  < — The  residual  standard  deviation  at  the  solution, 

RSD  = (RSS(8)/(Nnzw-NPAR))1/2 

where  Nnzw  is  the  number  of  observations  with  nonzero  weights. 

SDPV  < — The  vector  of  dimension  at  least  N that  contains  the  standard 

deviation  of  each  predicted  value  at  the  solution, 

SDPV(i)  = the  i1"^1  diagonal  element  of  [D»  VCV*  D^] 1 /2 

for  i = 1,  N,  where  D is  the  design  matrix,  D(i,j)  = x^(j) 

with  x^(j)  defined  in  §A,  and  DT  is  the  transpose  of  D. 

SDRES  < — The  vector  of  dimension  at  least  N that  contains  the  standardized 

*_  r_ 

residuals  at  the  solution,  i.e.,  the  icn  residual  divided  by  its 
estimated  standard  deviation, 

SDRES(i)  = RES(i)/[(RSD2/wt1)  “ SDPV(i)2]1/2  for  i = 1,  ...,  N. 

VCV  <--  The  matrix  of  dimension  at  least  NPAR  by  NPAR  that  contains  the 
variance-covariance  matrix  of  the  estimated  parameters  at  the 
solution, 

VCV  = RSD2 • (DT*  W»  D)”1 

where  W is  the  N by  N diagonal  matrix  of  weights, 

W = diagjwt-^,  i=l , ...,  N}  , 

and  D is  the  design  matrix,  D(i,j)  = x^(j)  with  x^(j)  defined  in 
§A,  and  is  the  transpose  of  D« 


WT 


X 


XM 


Y 


“">  The  vector  of  dimension  at  least  N that  contains  the  weights. 
Negative  weights  are  not  allowed  and  the  number  of  nonzero  weights 
must  equal  or  exceed  the  number  of  parameters  being  estimated.  A 
zero  weight  eliminates  the  corresponding  observation  from  the 
analysis,  although  the  residual,  the  predicted  value  and  the 
standard  deviation  of  the  predicted  value  of  a zero-weighted 
observation  are  still  computed.  [See  Appendix  B. ] 

— > The  vector  of  dimension  at  least  N that  contains  the  independent 
variable  used  to  construct  the  design  matrix  for  the  polynomial 
model. 

— > The  matrix  of  dimension  at  least  N by  NPAR  that  contains  the 
design  matrix,  i.e.,  the  matrix  whose  columns  are  the  independent 
variables  plus  a column  of  ones  if  a constant  term  is  being 
estimated. 


— > The  vector  of  dimension 
variable. 


at  least 


N that  contains 


the  dependent 
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E.  Computational  Methods 
E . 1 . The  Linear  Least  Squares  Algorithm 


The  linear  least  squares  estimation  subroutines  use  a modified 
Gram-Schmidt  algorithm  [Davis,  1962;  Walsh,  1962] . The  printed  output  for  the 
linear  least  squares  subroutines  has  been  modeled  on  the  linear  least  squares 
output  used  by  OMNITAB  II  [Hogben  et  al.  1971], 


E . 2 Computed  Results  and  Printed  Output 

The  argument  controlling  the  printed  output,  NPRT,  is  discussed  in  §D. 

The  output  from  the  linear  least  squares  estimation  subroutines  consists 
of  four  sections,  several  of  which  include  tables  summarizing  the  results.  In 
the  following  descriptions,  the  actual  table  headings  are  given  by  the 
underlined,  uppercase  phrases.  Results  which  correspond  to  input  or  returned 
arguments  are  identified  by  the  argument  name  in  uppercase  (not  underlined). 

Section  1 provides  the  following  information  for  each  observation,  i,  i = 1, 
. . . , N,  based  on  the  solution. 

® ROW ‘ the  row  number  of  the  observation. 

• PREDICTOR  VALUES:  the  values  for  up  to  the  first  three  columns  of  the 

independent  variable  (design  matrix).  For  subroutines  with  a 
user-supplied  model,  this  is  up  to  the  first  three  columns  of  the 
matrix  XM  (excluding  the  first  column  if  it  is  all  ones,  indicating  a 
constant  term);  for  the  polynomial  model  subroutines,  this  is  the 
variable  X. 

• DEPENDENT  VARIABLE:  the  values  of  the  dependent  variable,  Y. 

• PREDICTED  VALUE:  the  predicted  values,  PV,  from  the  fit. 

® STD  DEV  OF  PREP  VALUE:  the  standard  deviations  of  the  predicted 

values,  SDPV. 

® RESIDUAL s the  error  estimate,  RES. 

• STD  RES:  the  standardized  residual,  SDRES. 

o WEIGHT : the  user-supplied  weights,  WT,  printed  only  when  weighted 

analysis  is  performed. 
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Section  2 displays  the  following  plots  of  the  standardized  residuals. 

• The  standardized  residuals  versus  row  numbers. 

o The  standardized  residuals  versus  predicted  values. 

® The  autocorrelation  function  of  the  (non-standardized)  residuals. 

• The  normal  probability  plot  of  the  standardized  residuals. 

Section  3 provides  an  analysis  of  variance.  The  results  of  this  analysis 
depend,  upon  the  order  of  the  columns  of  the  design  matrix  unless  the 
columns  are  orthogonal . The  analysis  includes  the  following 
information. 

9 PAR  INDEX : the  index,  j,  of  the  parameter  being  examined,  8(j)* 

• SUM  OF  SQUARES  RED  DUE  TO  PAR:  SSj,  the  reduction  in  the  sum  of 

squares  due  to  fitting  8(j)  after  having  fit  parameters  8(0,  8(2), 

...»  8(j~l).  SSj  depends  on  the  order  of  the  parameters  unless  the 
design  matrix  has  orthogonal  columns.  This  is  a decomposition  of  the 
total  sum  of  squares,  TSS,  into  NPAR  + 1 parts 

NPAR 

TSS  = ( l SSj)  + RSS(S). 
j = l 

The  residual  sum  of  squares  and  total  sum  of  squares  is  also  listed  in 
this  column. 

• CUM  MS  RED:  the  cumulative  mean  square  reduction, 

3 

MSREDj  = l SSk/j  for  j = 1,  . ..,  NPAR. 
k=l 

• DF (MSRED) ; the  degrees  of  freedom  associated  with  the  cumulative  mean 
square  reduction  for  each  parameter,  DF(MSREDj)  = j for 
j = 1,  ...,  NPAR.  The  degrees  of  freedom  for  the  residuals, 
Nnzw~^Pj^R»  and  t*le  total  degrees  of  freedom,  Nnzw,  where  Nnzw  is  the 
number  of  observations  with  nonzero  weights,  are  also  listed  in  this 
column. 

® CUM  RES  MS:  the  cumulative  residual  mean  square, 

NPAR 

RMSj  = ( RSS(8 ) + l SSk)/(Nnzw-j)  for  j = 1,  ...,  NPAR. 
k=j  + l 

o DF(RMS ) : the  degrees  of  freedom  associated  with  the  cumulative 

residual  mean  square  for  each  parameter,  DF(RMSj)  = Nnzw-j  for 
j = 1 , . . . , NPAR. 
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9 PAR=0 , F and  PROB(F):  the  F-ratio  and  its  significance  level  under 

the  null  hypotheses  that  8(j)  is  zero  after  allowance  has  been  made 
for  parameters  8(1)  > 8(2),  8 ( j— 1 ) - This  F-ratio  is 

Fj  = SSj/RMS^jpAR  for  j = 1,  •••,  NPAR, 

with  1 and  Nnzw-NPAR  degrees  of  freedom.  The  significance  level 
listed  is  the  probability  of  exceeding  the  calculated  F-ratio  under 
the  null  hypothesis  that  the  corresponding  parameter,  8(j),  is  zero. 

• PARS=0,  F and  PROB(F) : the  F-ratio  and  its  significance  level  under 

the  null  hypothesis  that  parameters  8(j),  8(j+l),  • ••,  8(NPAR),  are 
zero  after  allowance  has  been  made  for  parameters  8(1),  8(2),  . .., 
8(j-l).  This  F-ratio  is 

NPAR 

Fi  = ( l SSk/(NPAR-j+l))/RMSNPAR  for  j = 1,  ...,  NPAR, 
k=j 

with  NPAR-j+1  and  Nnzw~NPAR  degrees  of  freedom.  The  significance 
level  listed  is  the  probability  of  exceeding  the  calculated  F-ratio 
under  the  null  hypothesis  that  all  of  the  parameters  8(j),  8 (j+1), 
...,  8 (NPAR)  are  zero. 

The  numerator  of  this  ratio  is  the  extra  sum  of  squares  accounted  for 
by  inclusion  of  the  terms  8(j)*x(j)  + 8( j+1) *x( j+1)  + ...  + 8(NPAR)» 
x(NPAR)  in  the  model,  divided  by  its  degrees  of  freedom;  the 
denominator  is  the  residual  mean  square  of  the  full  model.  This  ratio 
is  a means  of  comparing  the  extra  sum  of  squares  to  its  expected  value 
as  estimated  by  the  residual  mean  square.  When  the  terms  of  the  model 
have  a logical  order  of  entry,  this  series  of  F-tests  can  be  used  to 
judge  how  many  terms  should  be  included  in  the  model.  [See  Draper  and 
Smith,  1981,  pages  97  and  98.] 

Section  4 summarizes  the  following  information  about  the  final  parameter 
estimates  and  their  variances. 

o The  variance-covariance  matrix,  VCV , of  the  estimated  parameters,  and 
the  corresponding  correlation  matrix, 

r jk  = VCV( J,k)/(VCV( j, j)-VCV(k,k))1/2  for  j = 1,  ...,  NPAR 

and  k = 1,  ...,  NPAR. 

• ESTIMATES  FROM  FIT: 

° ESTIMATED  PARAMETER:  the  final  estimate  for  each  parameter, 

PAR(j)  for  j = 1,  ...,  NPAR. 

° SD  OF  PAR:  the  standard  deviation  of  the  estimated  parameter, 

( VCV( j, j)) 1 /2  for  j = 1,  ...,  NPAR. 

° T(PAR=0) : the  Student's  t statistic  under  the  null  hypothesis  that 

PAR(j)  is  actually  zero, 
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T(PAR=0) j = PAR(j )/(VCV(j ,j))1/2  for  j = 1,  NPAR. 

o PRQB (T) : the  two-sided  significance  level  of  T(PAR=0)j.  This  is 

the  probability  of  exceeding  the  given  t value  under  the  null 
hypothesis  that  the  parameter  PAR( j ) is  actually  zero. 

o ACC  DIG:  an  estimate  of  the  number  of  reliable  digits  in  the 

parameter  estimates,  i.e.,  an  indication  of  the  computational 
accuracy  of  the  solution.  A computationally  accurate  solution  will 
produce  values  between  DIGITS-2  and  DIGITS,  where  DIGITS  is  the 
number  of  decimal  digits  carried  by  the  user’s  computer  for  a single 
precision  value  when  the  single  precision  version  of  STARPAC  is 
being  used  and  is  the  number  carried  for  a double  precision  value 
otherwise.  Values  less  than  DIGITS-4  may  indicate  some 
computational  difficulty  such  as  poor  scaling  or  near  singularity. 

• ESTIMATES  FROM  FIT  OMITTING  LAST  PREDICTOR  VALUE;  ESTIMATED 
PARAMETER,  SD  OF  PAR,  T(PAR=0)  and  PROB(T)  values  for  a fit  omitting 
the  last  column  of  the  design  matrix  and  thus  omitting  the  last 
parameter  from  the  model. 

• The  residual  standard  deviation,  RSD. 

• The  residual  degrees  of  freedom,  Nnzw“NPAR,  where  Nnzw  is  the  number 
of  observations  with  nonzero  weights. 

o The  squared  multiple  correlation  coefficient, 

N 

__  l wti»  Y(i ) 

where  YrT  _ i=l 

w — — — . . 

N 

l wti 

i=l 

R2  is  a measure  of  how  well  the  fitted  equation  accounts  for  the  total 
variation  of  the  dependent  variable,  Y.  It  is  only  computed  when  the 
first  parameter  of  the  model  is  a constant,  i.e.,  when  the  elements  of 
the  first  column  of  the  design  matrix  are  all  equal. 


R = 1.0 


RSS(g) 


I Wtl  (Yd)  - Yj2 
i = l 


F . Examples 

User-Specified  Model  (Design  Matrix).  In  the  example  program  of  figure 
F-la,  LLS  is  used  to  compute  the  least  squares  solution  for  the  example  given 
on  pages  61-65  of  Daniel  and  Wood  [1971].  The  results  for  this  problem  are 
also  discussed  in  Draper  and  Smith  [1981],  pages  372  and  373.  Figures  F-lb 
through  F-le  show  the  four  pages  of  output  from  LLS. 

Polynomial  Model  (Design  Matrix).  In  the  example  program  of  figure  F-2a, 
LLSP  is  used  to  compute  the  least  squares  solution  for  the  example  given  on 
page  311  of  Miller  and  Freund  [1977].  Figures  F-2b  through  F-2e  show  the  four 
pages  of  output  from  LLSP. 
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Linear  Least  Squares 

With  User-Specified  Model  (Design  Matrix) 


MAIN  PROGRAM! 

c 

c 

c 

c 

c 

c 

c 

e 

c 


PROGRAM  EXANPL 

DEMONSTRATE  LIS  USING  SINGLE  PRECISION  VERSION  OF  STARPAC 
RUN  ON  CYBER  180/840. 

OUTPUT  UNIT  IS  6 (AUTOMATICALLY  EQUATED  TO  FILE  TAPE  6 ON  CYBERS) 
tSEE  CHAPTER  1#  SECTION  0.4] 

N.B « DECLARATION  OF  Y#  XH  AND  RES  RUST  BE  CHANGED  TO  DOUBLE  PRECISION 
IF  DOUBLE  PRECISION  VERSION  OF  STARPAC  IS  USED. 


REAL  Y( 30) » XM<30#5)#  RiSCIG} 

DOUBLE  PRECISION  DSTAM500) 

C 

COMMON  /CSTAK/  OSTAK 
C 

C SPECIFY  NECESSARY  DIMENSIONS 
C 

l OSTAK  • see 

IXK  « 10 

C 

C READ  NUMBER  OF  OBSERVATIONS  AND  NUMBER  OF  UNKNOWN  PARAHETERS 
C INDEPENDENT  VARIABLES 

C DEPENDENT  VARIABLES 

C 

READ  100»  N#  NPAR 

READ  101#  UXHU#Ji»  I*1#N»#  J*1»NPAR) 

READ  101#  (Yd)#  I®1,  N ) 

C 

C PRINT  TITLE  AND  CALL  LLS  TO  PERFORM  LINEAR  LEAST  SQUARES  ANALYSIS 
C 

WRITE  (6#  102) 

CALL  LLS  (Y#  XN»  N»  1XN#  NPAR#  RES#  LOSTAK) 

C 

STOP 

C 

C FQRNAY  STATEMENTS 

e 

100  FORMAT  (219) 

101  FORMAT  C21F1.0) 

102  FORMAT  C1RESULTS  FROM  STARPAC ( # 

• • LINEAR  LEAST  SQUARES  SUBROUTINE  LLS* ) 

END 

DATA!  21  4 


l 

i 

1 

1 

1 

1 

1 

1 

1 

1 

1 

1 

1 

1 

1 

1 

1 

1 

1 

1 

1 

86 

80 

75 

62 

62 

62 

62 

62 

98 

98 

56 

98 

98 

58 

50 

90 

50 

50 

50 

96 

70 

2? 

2? 

29 

24 

22 

23 

24 

24 

23 

18 

18 

17 

18 

19 

16 

18 

19 

19 

20 

20 

20 

69 

88 

90 

87 

87 

87 

93 

93 

87 

80 

89 

88 

82 

91 

89 

86 

72 

79 

80 

82 

91 

42 

IT 

37 

28 

IS 

18 

19 

20 

15 

14 

14 

13 

11 

12 

8 

7 

8 

8 

9 

15 

15 

Figure  F-la 

Example  program  using  LLS 
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Example  of  LLS  output 
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Example  of  LLS  output  (continued) 
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Example  of  LLS  output  (continued) 
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Example  of  LLS  output  (continued) 


Linear  Least  Squares 
With  Polynomial  Model  (Design  Matrix) 


MAIN  PROGRAM! 


PROGRAM  EXAMPL 

c 

C DEMONSTRATE  LLSP  USING  SINGLE  PRECISION  VERSION  OE  STARPAC 

C RUN  ON  CYBER  160/640. 

C 

C OUTPUT  UNIT  IS  6 (AUTOMATICALLY  EQUATED  TO  FILE  T A pE  6 ON  CYBERSJ 

C tSEE  CHAPTER  1»  SECTION  D.43 

C 

C N.B.  DECLARATION  OF  Ya  X AND  RES  MUST  BE  CHAN6ED  TO  DOUBLE  PRECISION 

C IF  DOUBLE  PRECISION  VERSION  OF  STARPAC  IS  USED. 

C 

REAL  Y ( 30 ) # X(30l>  RES ( 303 
DOUBLE  PRECISION  DSTAM500) 

C 

COMMON  /CSTAX/  DSTAK 
C 

C SPECIFY  NECESSARY  DIMENSIONS 

C 

LOSTAK  • 906 
C 

C READ  NUMBER  OF  OBSERVATIONS  AND  DEGREE  OF  THE  POLYNOMIAL  TO  BE  FIT 
C INDEPENDENT  AND  DEPENDENT  VARIABLES 

C 

READ  160a  Na  NDEG 

READ  101a  (XU»a  YU)  a I«1aN) 

c 

c PRINT  TITLE  AND  CALL  LLSP  TO  PERFORM  LINEAR  LEAST  SQUARES  ANALYSIS 

C 

WRITE  (6a  102) 

CALL  LLSP  (Ya  X#  N»  NOEGa  RESa  LOSTAK) 

C 

STOP 

C 

C FORMAT  STATEMENTS 

C 

100  FORMAT  (219) 

101  FORMAT  (2F5.1) 

102  FORMAT  C1RESULTS  OF  STARPAC8# 

* » LINEAR  LEAST  SQUARES  SUBROUTINE  LLSP8  J 

END 


DATA!  9 2 

0 e 6 12.0 

1.6  10.5 

2.0  19.0 

3.0  8.0 

4.0  7.0 

5.0  B.O 

6.0  7.9 

7.0  B.9 
B.O  9.0 


Figure  F-2a 


Example  program  using  LLSP 
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Example  of  LLSP  output 


UMCAR  HAS?  SQUARES  SSTINATIOM  WITH  POLTMOMIAl  MOOSl#  CONTINUED  STARPAC  2.00S  - OECEhBEA  t,  I9M 

SID  RfS  VS  ROM  NUMBER  STD  RES  VS  PREDICTED  VALUES 
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Example  of  LLSP  output  (continued) 


o 

o o 
© o 
• • 


s 

►- 

u 

*■9 

Q 


OK 

• <Si 

to  • 

•■3  «V) 

I 


© © 

IVS  <0 

k>  «n 

K=  © 

r»  w 

o « 


o « 

K « 
K=  #9 
K*>  <ft 
K « 

Kt>  #»9 
«0  <TO 

e® 
O *9 


o 


VD  6 

a 9 
iu  i 

K=  0 

tM  $ 
£ 6 
^ I 
« 9 
•«  8 
* 9 
6 

O « 

1*9  9 


O 

© 


< Q 

1 si 

O 9 

< «3 
« <8  IM 

oz« 

O <«€ 
tu  « 

X < **> 

© s 

U£  IU 

> 

© X <U 

« *=*> 

< «*> 
X ttt 

iUOW 
« © 

^ Mfl  €a9 


U 

ZWK 

^ 


» « « 
o < © 
u » w 


?? 


#a  o»  «w 
^ K®  K® 


eoo 
® © © 

e © ® 
9 


0 9 

M0  9*9 

K®  «•  srt 

K*  ® 

KOK 


© ® *4 
MOO 
• «r>  © 
• • • 
9 9 


WWW 

o oo 
© 0*  © 
OCM 
m>  ■&  m 
® m <® 
K OM 

*■43  © s© 


© 

U 


© ^ 

c=3  r3 


© © ** 
© © © 
© © © 


«4M  M 
©«*■*■€ 
• (ft  0* 
© ® © 
WK  « 
6 


© 

e 

U4 

KM  © 
#<K=  © 
© © © 
© © © 
© f4  <r 
© * <# 
» •#  # 
© 

© K# 

• • « 


WOW 
® « K4 

© © <T 

CM  o 
<#>**  © 
® ® © 
© © K9 


M MM  Cft 


© o 

0* 

*> 

K» 

« 

oO  C 

© 

• © 

I 

© 


w 


o 

u 


o a 
» © 
*»  IM 
< M 

« m 

> «*> 

© I* 
© 
G 


MO  U 

m*  X M 

© «/ 

© K 

o o « 


0) 

es! 

! 

0) 

u 

3 

bo 

"H 


8-22 


Example  of  LLSP  output  (continued) 


G.  Acknowledgments 


The  code  and  printed  output  for  the  linear  least  squares  subroutines  has 
been  modeled  on  the  linear  least  squares  code  and  output  used  by  OMNITAB  II 
[Hogben  et  al.  1971]. 
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CHAPTER  9 


NONLINEAR  LEAST  SQUARES 


A.  Introduction 


STARPAC  contains  16  user-callable  subroutines  for  nonlinear  least  squares 
regression*  Twelve  of  these  are  estimation  subroutines  that  compute  the  least 
squares  solution  as  described  below,  performing  either  weighted  or  unweighted 
regression  with  either  numerically  approximated  or  user-supplied  (analytic) 
derivatives.  The  estimation  subroutines  allow  three  levels  of  control  of  the 
computations  and  printed  output,  and  allow  the  user  to  specify  a subset  of  the 
parameters  to  be  treated  as  constants,  with  their  values  held  fixed  at  their 
input  values.  This  last  feature  allows  the  user  to  examine  the  results 
obtained  estimating  various  subsets  of  the  parameters  of  a general  model 
without  rewriting  the  model  subroutine  for  each  subset.  The  other  four 

subroutines  described  in  this  chapter  are  utility  procedures  which  choose 
optimum  step  sizes  for  numerically  approximating  the  derivative  and  which 
verify  the  correctness  of  user-supplied  (analytic)  derivatives. 

Each  of  the  subroutines  described  in  this  chapter  assumes  that  the 
observations  of  the  dependent  variable,  y^,  are  modeled  by 

y-j_  = fi(xi,$)  + for  i = 1,  ...»  N, 

where 

N is  the  number  of  observations; 

f^  is  the  function  (nonlinear  in  its  parameters)  that  models  the  i1"*1 

observation; 

x^  is  the  vector  of  the  M independent  variables  at  the  i*1*1  observation; 

g is  the  vector  of  the  NPAR  model  parameters;  and 

e i is  the  unobservable  random  error  in  the  ic^  observation,  which  is 

estimated  by  the  i*"*1  residual. 

The  least  squares  estimates  of  the  parameters,  g,  are  obtained  using  an 
iterative  procedure  that  requires  the  matrix  of  partial  derivatives  of  the 
model  with  respect  to  each  parameter, 

D(i,k)  = 3fi(xi,g)/9g(k)  for  i = 1,  ...,  N and  k = 1,  ...,  NPAR. 

The  derivative  matrix  may  be  supplied  analytically  or  approximated 
numerically . 

A 

The  least  squares  solution,  g,  is  that  which  minimizes  (with  respect  to 
g ) the  residual  sum  of  squares  function, 
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[e^.wti] 


N N 

RSS(B)  = I [Oi  - fi(xis6))2owti]  = l 
i=l  i=l 

where  carat  (* * ) denotes  the  estimated  quantity,  and 

wt^  is  the  weight  assigned  to  the  ic^  observation  (wt-^  = 1.0  in  the 

"unweighted"  case).  Appendix  B discusses  several  common  applications 
for  weighted  least  squares. 

The  user  must  supply  both  initial  values  for  the  parameters  and  the 
subroutine  NLSMDL  (described  in  §D)  used  to  compute  f Xj_  ,B£ ) » i = 1,  ...,  N, 
i.e.,  the  predicted  values  of  the  dependent  variable  given  the  independent 
variables  and  the  parameter  values  from  iteration  £ for  £ = 1,  2,  ...  . 
Initial  parameter  values  should  be  chosen  with  care,  since  good  values  can 
significantly  reduce  computing  time. 

STARPAC  provides  a variety  of  subroutines  to  accommodate  many  levels  of 
user  sophistication  and  problem  difficulty.  Users  are  directed  to  §B  for  a 
brief  description  of  the  subroutines.  The  declaration  and  CALL  statements  are 
given  in  §C,  and  the  subroutine  arguments  are  defined  in  §D.  The  algorithms 
used  and  the  output  produced  by  these  subroutines  are  discussed  in  §E.  Sample 
programs  and  their  output  are  shown  in  §F. 


B . Subroutine  Descriptions 


B. 1 Nonlinear  Least  Squares  Estimation  Subroutines 

The  simplest  of  the  12  nonlinear  least  squares  estimation  subroutines, 
NLS,  requires  neither  user-supplied  weights  nor  analytic  derivatives.  The 
estimated  results  and  a variety  of  statistics  are  automatically  summarized  in 
a five-part  printed  report,  and  the  estimated  parameters  and  residuals  are 
returned  to  the  user  via  the  subroutine  argument  list  (level  one  control, 
described  below).  Most  nonlinear  least  squares  problems  can  be  solved  using 
NLS. 


The  other  11  estimation  subroutines  add  the  weighting,  derivative  and 
level  two  and  three  control  features  both  singly  and  in  combination,  providing 
greater  flexibility  to  the  user  at  the  price  of  less  simplicity.  These 
features  are  indicated  by  the  suffix  letter(s)  on  the  subroutine  name  (e.g., 
NLS_S  and  NLSWDC). 

• Suffix  W indicates  user-supplied  weights. 

• Suffix  D indicates  user-supplied  (analytic)  derivatives. 

© Suffix  C indicates  level  two  control  of  the  computations. 

© Suffix  S indicates  level  three  control  of  the  computations. 
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The  three  levels  of  computation  and  printed  output  control  are  as 
f ollows. 

o In  level  one,  a five-part  printed  report,  discussed  in  detail  in 
§E.2.a,  is  automatically  provided  and  the  estimated  model  parameters 
and  residuals  are  returned  to  the  user  via  the  argument  list. 

• Level  two  also  returns  the  estimated  parameters  and  residuals,  and, 
in  addition,  allows  the  user  to  supply  arguments  to  indicate 

- a subset  of  the  model  parameters  to  be  treated  as  constants, 
with  their  values  held  fixed  at  their  input  values; 

~ either  the  step  sizes  used  to  compute  the  numerical  approxima- 
tions to  the  derivative,  or,  when  user-supplied  analytic 
derivatives  are  used,  whether  they  will  be  checked; 

- the  maximum  number  of  iterations  allowed; 

- the  convergence  criteria; 

- the  scale  (i.e. , the  typical  size)  of  each  parameter; 

- the  maximum  change  allowed  in  the  parameters  at  the  first 
iteration; 

- how  the  variance-covariance  matrix  is  to  be  approximated;  and 

- the  amount  of  printed  output  desired. 

© Level  three  has  all  the  features  of  level  two,  and,  in  addition 
returns  the  following  estimated  values  via  the  argument  list; 

- the  number  of  nonzero  weighted  observations  (only  when  a 
weighted  analysis  is  performed); 

- the  number  of  parameters  actually  estimated; 

- the  residual  standard  deviation; 

- the  predicted  values; 

--  the  standard  deviations  of  the  predicted  values; 

- the  standardized  residuals;  and 

- the  variance-covariance  matrix  of  the  estimated  parameters. 


B «2  Derivative  Step  Size  Selection  Subroutines 


When  the  partial  derivatives  used  in  the  nonlinear  least  squares  solution 
are  not  available  analytically,  STARPAC  subroutines  approximate  them  numeri- 
cally. In  this  case,  the  subroutines  can  select  optimum  step  sizes  for 
approximating  the  derivatives.  [See  §E.l.b.]  The  user  also  has  the  option  of 
computing  these  step  sizes  independently  of  the  estimation  process  by  calling 
either  of  the  two  step  size  selection  subroutines  directly.  For  example,  when 
planning  to  use  the  parameter  fixing  capability  [argument  IFIXED]  to  examine 
several  subsets  of  the  parameters  of  a general  model,  computing  the  step  sizes 
first  and  passing  them  to  the  estimation  subroutine  is  more  efficient  than 
recomputing  them  each  time  the  estimation  subroutine  is  called. 

The  simplest  of  the  two  user-callable  step  size  selection  subroutines, 
STPLS,  summarizes  the  step  size  selection  information  for  each  parameter  in  a 
printed  report  and  returns  the  step  sizes  to  the  user  via  the  subroutine 
argument  list. 
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The  second  step  size  selection  subroutine,  STPLSC,  differs  from  STPLS 
only  in  that  it  enables  the  user  to  supply  arguments  to  indicate 

- the  number  of  reliable  digits  in  the  model  results; 

- the  number  of  exemptions  allowed  by  the  acceptance  criteria, 
specified  as  a proportion  of  the  total  number  of  observa- 
tions (see  §E.l.b); 

- the  scale  (i.e. , the  typical  size)  of  each  parameter;  and 
~ the  amount  of  printed  output  desired. 

B . 3 Derivative  Checking  Subroutines 


When  the  partial  derivatives  used  in  the  nonlinear  least  squares  solution 
are  available  analytically,  the  user  can  code  them  for  use  by  the  estimation 
subroutines.  [See  §D,  argument  NLSDRV.]  Because  coding  errors  are  a common 
problem  with  user-supplied  derivatives,  the  STARPAC  estimation  subroutines 
automatically  check  the  validity  of  the  user-supplied  derivative  code  by 
comparing  its  results  to  numerically  approximated  values  for  the  derivative. 
When  the  results  are  questionable,  the  checking  procedure  attempts  to 
determine  whether  the  problem  lies  with  the  user's  code  or  with  the  accuracy 
of  the  numerical  approximation.  [See  §E.l.c.]  Although  the  checking  proce- 
dure is  automatically  available  to  the  estimation  subroutines  which  accept 
user-supplied  derivatives,  the  user  may  want  to  check  the  derivative  code 
independently  of  the  estimation  process.  In  these  cases,  the  user  can  call 
either  of  the  two  derivative  checking  subroutines  directly,  and  suppress 
checking  by  the  estimation  subroutines.  [See  §D,  argument  IDRVCK.] 

The  simplest  of  the  two  derivative  checking  subroutines,  DCK.LS, 
summarizes  the  results  of  the  check  in  a printed  report. 

The  second  of  the  derivative  checking  subroutine,  DCKLSC,  differs  from 
DCKLS  only  in  that  it  enables  the  user  to  supply  arguments  to  indicate 

- the  number  of  reliable  digits  in  the  model  results; 

- the  agreement  tolerance; 

- the  scale  (i.e.,  the  typical  size)  of  each  parameter; 

- the  row  at  which  the  derivative  is  to  be  checked;  and 

- the  amount  of  printed  output  desired. 


C . Subroutine  Declaration  and  CALL  Statements 

NOTE:  Argument  definitions  and  sample  programs  are  given  in  §D  and  §F, 
respectively.  The  conventions  used  to  present  the  following  declaration  and 
CALL  statments  are  given  in  chapter  1,  §B,  and  §D. 
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Nonlinear  Least  Squares  Estimation  Subroutines 


The  <basic  declaration  block>  identifies  declaration  statements  that  are 
needed  by  all  of  the  nonlinear  least  squares  estimation  subroutines.  The  user 
should  substitute  the  following  four  statements  for  each  occurrence  of  <basic 
declaration  block>  given  below. 

<real>  Y (n),  XM PAR (npar),  RES(n) 

DOUBLE  PRECISION  DSTAK (Idstak) 

COMMON  /CSTAK/  DSTAK 
EXTERNAL  NLSMDL 


NLS : Compute  and  print  a five-part  weighted  nonlinear  least  squares 

analysis  with  numerically  approximated  derivatives;  return  parameter 
estimates  and  residuals 

<basic  declaration  block> 


CALL  NLS  (Y,  XM,  N,  M,  IXM,  NLSMDL,  PAR,  NPAR,  RES,  LDSTAK) 


NLSC : Compute  and  optionally  print  a five-part  unweighted  nonlinear  least 

squares  analysis  with  numerically  approximated  derivatives  using 
user- supplied  control  values;  return  parameter  estimates  and 
residuals 

<basic  declaration  block> 

INTEGER  IFIXED (npar) 

<real>  STP (npar),  STOPSS,  STOPP,  SCALE (npar) , DELTA 


CALL  NLSC  (Y,  XM,  N,  M,  IXM,  NLSMDL,  PAR,  NPAR,  RES,  LDSTAK, 

1 IFIXED,  STP,  MIT,  STOPSS,  STOPP,  SCALE,  DELTA,  IVAPRX,  NPRT) 
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NLSS:  Compute  and  optionally  print  a five-part  unweighted  nonlinear  least 

squares  analysis  with  numerically  approximated  derivatives  using 
user-supplied  control  values;  return  parameter  estimates s residuals , 
number  of  nonzero  weights , number  of  parameters  estimated > residual 
standard  deviation > predicted  valuess  standard  deviations  of  the 
predicted  values  and  variance-covariance  matrix  of  the  estimated 
parameters 

<basic  declaration  block> 

INTEGER  IFIXED (npar) 

<real>  STP (npar),  STOPSS,  STOPP,  SCALE (npar) > DELTA 
<real>  RSD,  PV(n),  SDPV(n),  SDRES(n),  VC V (npar es  npar e) 


CALL  NLSS  (Y,  XM,  N,  M,  IXM,  NLSMDL,  PAR,  NPAR,  RES,  LDSTAK, 

1 IFIXED,  STP,  MIT,  STOPSS,  STOPP,  SCALE,  DELTA,  IVAPRX,  NPRT, 

2 NPARE,  RSD,  PV,  SDPV,  SDRES,  VCV,  IVCV) 


NLSW:  Compute  and  print  a five-part  weighted  nonlinear  least  squares 

analysis  with  numerically  approximated  derivatives ; return  parameter 
estimates  and  residuals 

<basic  declaration  block> 

<real>  WT(n) 


CALL  NLSW  (Y,  WT,  XM,  N,  M,  IXM,  NLSMDL,  PAR,  NPAR,  RES,  LDSTAK) 


NLSWC:  Compute  and  optionally  print  a five-part  weighted  nonlinear  least 

squares  analysis  with  numerically  approximated  derivatives  using 
user-supplied  control  values;  return,  parameter  estimates  and  residuals 

<basic  declaration  block> 

INTEGER  IFIXEL(npar) 

<real>  WT(n) 

<real>  STP(npar),  STOPSS,  STOPP,  SCALE(npar) , DELTA 


CALL  NLSWC  (Y,  WT,  XM,  N,  M,  IXM,  NLSMDL,  PAR,  NPAR,  RES,  LDSTAK, 
1 IFIXED,  STP,  MIT,  STOPSS,  STOPP,  SCALE,  DELTA,  IVAPRX,  NPRT) 
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NLSWS: 


Compute  and  optionally  print  a five-part  weighted  nonlinear  least 
squares  analysis  with  numerically  approximated  derivatives  using 
user-supplied  control  values;  return  parameter  estimates , residuals, 
number  of  nonzero  weights,  number  of  parameters  estimated,  residual 
standard  deviation,  predicted  values,  standard  deviations  of  the 
predicted  values  and  variance-covariance  matrix  of  the  estimated 
parameters 

<basic  declaration  block> 

INTEGER  IFIXED (npar) 

<real>  WT(n) 

<real>  STP( npar),  STOPSS,  STOPP,  SCALE(npar^),  DELTA 
<real>  RSD,  PV(rc),  SDPV(n),  SDRES(n),  VC V (npar  e,  npar  e) 


CALL  NLSWS  'Y,  WT,  XM,  N,  M,  IXM,  NLSMDL,  PAR,  NPAR,  RES,  LDSTAK, 

1 IFIXED,  STP,  MIT,  STOPSS,  STOPP,  SCALE,  DELTA,  IVAPRX,  NPRT, 

2 NNZW,  NPARE,  RSD,  PV,  SDPV,  SDRES , VCV , IVCV) 


NLSD : Compute  and  print  a five-part  unweighted  nonlinear  least  squares 

analysis  with  user- supplied  derivatives;  return  parameter  estimates 
and  residuals 

<basic  declaration  block> 

EXTERNAL  NLSDRV 


CALL  NLSD  (Y,  XM,  N,  M,  IXM,  NLSMDL,  NLSDRV,  PAR,  NPAR,  RES, 
1 LDSTAK) 


NLSDC:  Compute  and  optionally  print  a five-part  unweighted  nonlinear  least 

squares  analysis  with  user- supplied  derivatives  using  user- supplied 
control  values;  return  parameter  estimates  and  residuals 

<basic  declaration  block> 

EXTERNAL  NLSDRV 
INTEGER  IFIXED (npar) 

<real>  STOPSS,  STOPP,  S C ALE (npar ) , DELTA 


CALL  NLSDC  (Y,  XM,  N,  M,  IXM,  NLSMDL,  NLSDRV,  PAR,  NPAR,  RES, 

1 LDSTAK,  IFIXED,  IDRVCK,  MIT,  STOPSS,  STOPP,  SCALE,  DELTA, 

2 IVAPRX,  NPRT) 


9-7 


NLSDS:  Compute  and  optionally  print  a five-part  unweighted  nonlinear  least 

squares  analysis  with  user- supplied  derivatives  using  user-supplied 
control  values;  return  parameter  estimates,  residuals,  number  of 
parameters  estimated,  residual  standard  deviation,  predicted  values, 
standard  deviations  of  the  predicted  values  and  variance-covariance 
matrix  of  the  estimated  parameters 

<basic  declaration  block> 

EXTERNAL  NLSDRV 
INTEGER  IFIXED (npar) 

<real>  STOPSS,  STOPP,  SCALE (npar) , DELTA 

<real>  RSD,  P V(n),  SDPV(n),  SDRES(n),  VCV (npare,  npare ) 


CALL  NLSDS  (Y,  XM,  N,  M,  IXM,  NLSMDL,  NLSDRV,  PAR,  NPAR,  RES, 

1 LDSTAK,  IFIXED,  IDRVCK,  MIT,  STOPSS,  STOPP,  SCALE,  DELTA, 

2 IVAPRX,  NPRT,  NPARE,  RSD,  PV,  SDPV,  SDRES,  VCV,  IVCV) 


NLSWD:  Compute  and  print  a five-part  weighted  nonlinear  least  squares 

analysis  with  user- supplied  derivatives;  return  parameter  estimates 
and  residuals 

<basic  declaration  block> 

EXTERNAL  NLSDRV 
<real>  WT(n) 


CALL  NLSWD  (Y,  WT,  XM,  N,  M,  IXM,  NLSMDL,  NLSDRV,  PAR,  NPAR,  RES, 
1 LDSTAK) 


NLSWDC : Compute  and  optionally  print  a five-part  weighted  nonlinear  least 
squares  analysis  with  user-supplied  derivatives  using  user- supplied 
control  values;  return  parameter  estimates  and  residuals 

<basic  declaration  block> 

EXTERNAL  NLSDRV 
INTEGER  IFIXED(npar’) 

<real>  WT(n) 

<real>  STOPSS,  STOPP,  SCALE(npar») , DELTA 


CALL  NLSWDC  (Y,  WT,  XM,  N,  M,  IXM,  NLSMDL,  NLSDRV,  PAR,  NPAR,  RES, 

1 LDSTAK,  IFIXED,  IDRVCK,  MIT,  STOPSS,  STOPP,  SCALE,  DELTA, 

2 IVAPRX,  NPRT) 
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NLSWDS:  Compute  and  optionally  print  a five-part  weighted  nonlinear  least 
squares  analysis  with  user-supplied  derivatives  using  user- supplied 
control  values;  return  parameter  estimates , residuals,  number  of 
nonzero  weights,  number  of  parameters  estimated,  residual  standard 
deviation,  predicted  values,  standard  deviations  of  the  predicted 
values  and  variance- covariance  matrix  of  the  estimated  parameters 

<basic  declaration  block> 

EXTERNAL  NLSDRV 
INTEGER  IFIXED(npar) 

<real>  WT(n) 

<real>  STOPSS,  STOPP,  SCALE(npar’) , DELTA 

<real>  RSD,  PV(rc),  SDPV(n),  SDRES(n),  VC M (npar e,  npar e) 


CALL  NLSWDS  (Y,  WT,  XM,  N,  M,  IXM,  NLSMDL,  NLSDRV,  PAR,  NPAR,  RES, 

1 LDSTAK,  IFIXED,  IDRVCK,  MIT,  STOPSS,  STOPP,  SCALE,  DELTA, 

2 IVAPRX , NPRT,  NNZW,  NPARE,  RSD,  PV,  SDPV,  SDRES , VCV , IVCV) 


Step  Size  Selection  Subroutines 

STPLS : Compute  and  print  optimum  step  sizes  for  numerically  approximating 

derivatives;  return  selected  step  sizes 

<real>  XM(n,/7z),  PAR (npar),  STP(npar) 

DOUBLE  PRECISION  DSTAK (Idstak) 

COMMON  / CSTAK/  DSTAK 
EXTERNAL  NLSMDL 


CALL  STPLS  (XM,  N,  M,  IXM,  NLSMDL,  PAR,  NPAR,  LDSTAK,  STP) 


STPLSC : Compute  and  optionally  print  optimum  step  sizes  for  numerically 
approximating  derivatives  using  user-supplied  control  values;  return 
selected  step  sizes 

<real>  XM (n,m),  PAR (npar),  STP  (npar) 

<real>  EXMPT,  SCALE (npar) 

DOUBLE  PRECISION  DSTAK  {.Idstak) 

COMMON  /CSTAK/  DSTAK 
EXTERNAL  NLSMDL 


CALL  STPLSC  (XM,  N,  M,  IXM,  NLSMDL,  PAR,  NPAR,  LDSTAK,  STP, 
1 NETA,  EXMPT,  SCALE,  NPRT) 
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Derivative  Checking  Subroutines 


DCKLS:  Perform  and  print  derivative  checking  analysis;  return  error  code 

<real>  XM (n  ,m) , PAR(npar») 

DOUBLE  PRECISION  DSTAK {Idstak) 

COMMON  /CSTAK/  DSTAK 
EXTERNAL  NLSMDL,  NLSDRV 


CALL  DCKLS  (XM,  N,  M,  IXM,  NLSMDL,  NLSDRV,  PAR,  NPAR,  LDSTAK) 


DCKLSC:  Perform  and  optionally  print  derivative  checking  analysis  using 
user- supplied  control  values;  return  error  code 

<real>  XM(n,77z)>  PAR (jipar) 

<real>  SCALE  (jipar) 

DOUBLE  PRECISION  DSTAK {Idstak) 

COMMON  /CSTAK/  DSTAK 
EXTERNAL  NLSMDL,  NLSDRV 


CALL  DCKLSC  (XM,  N,  M,  IXM,  NLSMDL,  NLSDRV,  PAR,  NPAR,  LDSTAK, 
1 NETA,  NTAU,  SCALE,  NROW,  NPRT) 


D.  Dictionary  of  Subroutine  Arguments  and  COMMON  Variables 

NOTE?  — > indicates  that  the  argument  is  input  to  the  subroutine  and  that 

the  input  value  is  preserved; 

<—  indicates  that  the  argument  is  returned  by  the  subroutine; 

<->  indicates  that  the  argument  is  input  to  the  subroutine  and  that 
the  input  value  is  overwritten  by  the  subroutine; 

— indicates  that  the  argument  is  input  to  some  subroutines  and  is 
returned  by  others; 

***  indicates  that  the  argument  is  a subroutine  name; 

° ° • indicates  that  the  variable  is  passed  via  COMMON. 

D <--  The  matrix  of  exact  dimension  N by  NPAR  that  contains  the  partial 

derivatives  of  the  model  with  respect  to  each  parameter, 
PAR(k),  k = 1,  ...,  NPAR.  This  argument  is  used  within  derivative 
subroutine  NLSDRV  [see  argument  NLSDRV  below]. 

DELTA  “■>  The  maximum  scaled  change  allowed  in  the  parameters  at  the  first 
iteration,  i.e. , 6q.  [See  §E.l.a.]  The  default  value  is  100.0. 
When  DELTA  <0.0  or  when  DELTA  is  not  an  argument  of  the 

— continued — 
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subroutine  CALL  statement  the  default  value  is  used.  A smaller 
value  of  DELTA  may  be  appropriate  if,  at  the  first  iteration,  the 
computation  of  the  predicted  values  from  the  user’s  model  subrou- 
tine produces  an  arithmetric  overflow  or  the  parameters  leave  the 
region  of  interest  in  parameter  space.  A reasonable  alternative 
to  the  default  value  of  DELTA  is  an  upper  bound  to  the  scaled 
change  that  the  estimated  parameters  should  be  allowed  to  make  on 
the  first  iteration, 

DELTA  = min{  lA^xBCk)  | /SCALE(k),  for  k = 1,  ...,  NPAR} 

where  A^BCk)  is  the  maximum  change  allowed  for  the  kth  parameter 
at  the  first  iteration. 

DSTAK  ee*  The  DOUBLE  PRECISION  vector  in  COMMON  /CSTAK/  of  dimension  at 
least  LDSTAK.  DSTAK  provides  workspace  for  the  computations.  The 
first  LDSTAK  locations  of  DSTAK  will  be  overwritten  during 

subroutine  execution. 

EXMPT  — > The  proportion  used  to  compute  the  number  of  observations, 

a = EXMPT»N,  for  which  the  forward  difference  quotient  derivative 
with  respect  to  a given  parameter  is  exempted  from  meeting  the 
acceptance  criteria  for  step  size  selection.  [See  §E.l.b.]  The 
default  value  for  EXMPT  is  0.1  (10  percent).  When  the  user- 

supplied  value  is  outside  the  range  [0.0,  1.0] , or  when  EXMPT  is 
not  an  argument  of  the  subroutine  CALL  statement,  the  default 
value  is  used. 

IDRVCK  — > The  indicator  variable  used  to  designate  whether  or  not  the 

user-supplied  derivative  subroutine  is  to  be  checked.  When 

IDRVCK  $ 0 the  derivative  is  checked,  and  when  IDRVCK  =0  it  is 
not.  The  default  value  is  IDRVCK  * 0.  When  IDRVCK  is  not  an 
argument  of  the  subroutine  CALL  statement  the  default  value  is 
used. 

IERR  An  error  flag  returned  in  COMMON  /ERRCHK/.  [See  chapter  1,  §D. 5. ] 

Note  that  using  (or  not  using)  the  error  flag  will  not  affect  the 
printed  error  messages  that  are  automatically  provided  even  when 
the  user  has  suppressed  the  normal  printed  output. 

For  the  estimation  subroutines: 

IERR  = 0 indicates  that  no  errors  were  detected,  and  that  the 
iterations  converged  satisfactorily. 

IERR  = 1 indicates  that  improper  input  was  detected. 

IERR  = 2 indicates  that  the  computation  of  the  residual  sum  of 
squares  using  the  initial  parameter  values  produced  an 
arithmetic  overflow.  The  user  should  reduce  the  size 
of  DELTA  or  should  supply  new  starting  values. 

— continued — 
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IERR  = 3 indicates  that  the  model  is  computationally  singular, 
which  means  the  model  has  too  many  parameters  near  the 
solution.  The  user  should  examine  the  model  and  data 
to  determine  and  remove  the  cause  of  the  singularity. 

IERR  = 4 indicates  that  at  least  one  of  the  standardized 

residuals  could  not  be  computed  because  its  standard 

deviation  was  zero.  The  validity  of  the  covariance 
matrix  is  questionable. 

IERR  = 5 indicates  false  convergence.  [See  §E.l.a.] 

IERR  = 6 indicates  that  convergence  was  not  reached  in  the 

allowed  number  of  iterations  or  model  subroutine  calls. 
[See  argument  MIT.] 

IERR  = 7 indicates  that  the  variance-covariance  matrix  could  not 
be  computed. 

For  the  step  size  selection  subroutines. 

IERR  = 0 indicates  that  no  errors  were  detected,  and  that  all 
the  step  sizes  satisfied  the  selection  criteria. 

IERR  = 1 indicates  that  improper  input  was  detected. 

IERR  = 2 indicates  that  one  or  more  of  the  step  sizes  did  not 
satisfy  the  selection  criteria. 

For  the  derivative  checking  subroutines: 

IERR  = 0 indicates  that  no  errors  were  detected,  and  that  the 
user-supplied  derivative  code  appears  to  be  correct. 

IERR  = 1 indicates  that  improper  input  was  detected. 

IERR  = 2 indicates  that  the  user-supplied  derivative  code  and 
numerical  derivatives  do  not  agree  for  at  least  one 
parameter,  but  that  in  each  case  of  disagreement  the 
accuracy  of  the  numerical  derivatives  is  questionable. 
Further  testing  is  suggested. 

IERR  = 3 indicates  that  the  user-supplied  derivative  code  and 
numerical  derivatives  do  not  agree  for  at  least  one 
parameter,  and  in  at  least  one  instance  of  disagreement 
there  is  no  reason  to  doubt  the  numerical  derivatives. 

IFIXED  ™>  The  vector  of  dimension  at  least  NPAR  that  contains  values  used  to 
indicate  whether  the  corresponding  parameter  in  PAR  is  to  be 
treated  as  a fixed  constant  or  is  to  be  estimated.  If 

— continued — 
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IFIXED(I)  > 0,  PAR(I)  will  be  held  fixed  at  its  input  value;  if 
IFIXED(I)  = 0,  PAR(I)  will  be  estimated  using  the  least  squares 
procedure  described  in  §A.  The  default  values  are  IFIXED(I)  = 0, 
I = 1,  . ..,  NPAR,  i.e.,  all  parameters  are  estimated.  When 

IFIXED(l)  < -1 , or  when  IFIXED  is  not  an  argument  of  the 
subroutine  CALL  statement,  the  default  value  will  be  used. 

IVCV  -->  The  exact  value  of  the  first  dimension  of  the  matrix  VCV  as 
specified  in  the  calling  program. 

IVAPRX  — > The  indicator  variable  used  to  specify  how  the  variance-covariance 
matrix,  VCV,  is  to  be  approximated.  Three  approximations  are 
available: 

At 

(1)  VCV  = RSD2* (DT.W«D)~1 

(2)  VCV  = RSD2 • H_1 

At,  At, 

(3)  VCV  = rsd2«h-1. (dt.w*d)«h-1 
where 

At.  A^  N At  A*  At,  At 

H = DT.W»D  + { l ei*wti»  (a2ei/ag  (j  )ae  (k))  for  j 
i=l  and  k 

W is  an  N by  N diagonal  matrix  of  weights, 

W = diag{wt^,  i = 1,  ...,  N} , 

when  a weighted  analysis  is  performed,  and  is  the  identity  matrix 

A 

otherwise,  and  D is  the  matrix  that  contains  the  partial 

derivatives  of  the  model  with  respect  to  each  parameter. 

A 

T 

Approximation  (1)  is  based  on  the  assumption  that  H ~ D • W» D 
because  the  residuals  are  sufficiently  small  at  the  solution; 

approximation  (2)  is  based  on  the  assumption  that  the  necessary 

conditions  for  asymptotic  maximum  likelihood  theory  have  been  met; 
and  approximation  (3)  is  based  on  the  assumption  that  the 
necessary  conditions  for  asymptotic  maximum  likelihood  theory  may 
be  violated.  The  results  of  a recent  study  by  Donaldson  and 

Schnabel  [1985]  indicate  that  approximation  (1)  is  preferable 
because  it  is  simple,  less  expensive,  more  numerically  stable  and 
at  least  as  accurate  as  approximations  (2)  and  (3).  However,  all 
approximations  to  the  variance-covariance  matrix  are  subject  to 
sampling  variation  because  they  are  computed  using  the  estimated 
parameter  values.  The  variance-covariance  matrix  computed  for  any 
particular  nonlinear  least  squares  solution  should  thus  be 
regarded  as  only  a rough  estimate  [Bard,  1974;  Donaldson  and 
Schnabel,  1985] . 


= 1 , . . o , NPAR 
= 1 , . . . , NPAR}  ; 


— continued — 
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If  IVAPRX  = 1 or  4 then  approximation  (1)  is  used; 

= 2 or  5 then  approximation  (2)  is  used;  and 

= 3 or  6 then  approximation  (3)  is  used. 

If  IVAPRX  = 1,  2,  or  3,  then,  when  user-supplied  analytic 

derivatives  are  available  [see  argument  NLSDRV] , they  are  used  to 
compute  VCV;  if  IVAPRX  =4,  5,  or  6,  then  only  the  predicted 

values  from  the  model  subroutine  are  used  to  compute  VCV.  When 

analytic  derivatives  are  available,  options  1,  2,  or  3,  will 

generally  result  in  a faster,  more  accurate  computation  of  VCV. 

The  default  value  for  IVAPRX  is  1.  When  argument  IVAPRX  is 
outside  the  range  [1,  6],  or  when  IVAPRX  is  not  an  argument  of  the 
subroutine  CALL  statement,  then  the  default  value  will  be  used. 

IXM  ■-->  The  exact  value  of  the  first  dimension  of  the  matrix  XM  as 
specified  in  the  calling  program. 

LDSTAK  -->  The  length  of  the  DOUBLE  PRECISION  workspace  vector  DSTAK . LDSTAK 
must  equal  or  exceed  the  appropriate  value  given  below,  where  if 

the  single  precision  version  of  STARPAC  is  being  used  P = 0.5, 

otherwise  P = 1.0.  [See  chapter  1,  §B.] 

For  NLS,  NLSC , NLSS,  NLSW,  NLSWC  and  NLSWSs 

LDSTAK  > 27  + max( IS* (N+NPAR) , 30+NPARE}  + 

max { I S • 1 0 • N , 9 4+N • ( 3+NPAR )+( 3 * NPARE2 +3  7 * NPARE ) /2 } • P 

with  IS  = 1 if  default  values  are  used  for  the  derivative  step 
sizes,  and  IS  = 0 otherwise. 

For  NLSD,  NLSDC , NLSDS,  NLSWD,  NLSWDC  and  NLSWDSj 

LDSTAK  > 45  + NPAR  + ( 94+N« (3+NPAR )+( 3 • NPARE2+35* NPARE) fl) • P 

For  STPLS  and  STPLSC: 

LDSTAK  > 27  + (N+NPAR)  + 10»N«P 

For  DCKLS  and  DCKLSC: 

LDSTAK  > 14  + NPAR  + (N* NPAR+N+NPAR) • P 

M — > The  number  of  independent  variables,  i.e.,  the  number  of  columns 

of  data  in  XM. 

MIT  — > The  maximum  number  of  iterations  allowed.  This  argument  is  also 

used  to  compute  the  maximum  number  of  model  subroutine  calls, 

( 2 * MI T ) . The  iterations  will  stop  if  either  limit  is  reached, 
although,  as  a rule,  the  maximum  number  of  iterations  will  be 
reached  first.  The  default  value  for  the  maximum  number  of 
iterations  is  21.  When  MIT  < 0 or  when  MIT  is  not  an  argument  of 
the  subroutine  CALL  statement  the  default  value  will  be  used. 
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N 


— > The  number  of  observations. 


NETA  -->  The  number  of  reliable  decimal  digits  in  the  predicted  values  (PV) 
computed  by  the  user's  model  subroutine.  The  default  value  for 
NETA  is  experimentally  determined  by  the  procedure  described  in 
Appendix  C.  The  default  value  will  be  used  when  NETA  is  not  an 
argument  in  the  subroutine  CALL  statement,  or  when  the 
user-supplied  value  of  NETA  is  outside  the  range  [1,  DIGITS], 
where  DIGITS  is  the  number  of  decimal  digits  carried  by  the  user's 
computer  for  a single  precision  value  when  the  single  precision 
version  of  STARPAC  is  being  used  and  is  the  number  carried  for  a 
double  precision  value  otherwise. 

NLSDRV  ***  The  name  of  the  user-supplied  subroutine  that  computes  the  partial 
derivative  matrix  (Jacobian).  This  argument  must  be  listed  in  an 
EXTERNAL  statement  in  the  program  which  calls  the  STARPAC 
estimation  or  derivative  checking  subroutine.  The  form  of  the 
derivative  subroutine  argument  list  and  dimensioning  statements 
must  be  exactly  as  shown  below,  although  if  there  is  only  one 
independent  variable  (M  = 1),  XM  may  be  declared  to  be  a vector 
with  dimension  IXM. 

SUBROUTINE  NLSDRV  (PAR,  NPAR,  XM,  N,  M,  IXM,  D) 

<real>  PAR (NPAR) , XM(IXM,M),  D(N,NPAR) 

< Computations  for  D(I,J),  1=1,  N and  J = 1,  NPAR  > 

RETURN 

END 

NLSMDL  ***  The  name  of  the  user-supplied  subroutine  that  computes  the 
predicted  value  of  the  dependent  variable  given  the  independent 
variables  and  the  current  values  of  the  model  parameters.  This 
argument  must  be  listed  in  an  EXTERNAL  statement  in  the  program 
which  calls  the  STARPAC  estimation,  step  size  selection,  and/or 
derivative  checking  subroutines.  The  form  of  the  model  subroutine 
argument  list  and  dimensioning  statements  must  be  exactly  as  shown 
below,  although  if  there  is  only  one  independent  variable  (M  = 1), 
XM  may  be  declared  to  be  a vector  with  dimension  IXM. 

SUBROUTINE  NLSMDL  (PAR,  NPAR,  XM,  N,  M,  IXM,  PV) 

<real>  PAR (NPAR) , XM(IXM,M),  PV(N) 

< Computations  for  PV(I),  1=1,  ...,  N > 

RETURN 

END 

NNZW  < — ■ The  number  of  observations  with  nonzero  weights.  N.B.  This  value 

is  returned  by  the  estimation  subroutines. 
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NPAR 


NPARE 


NPRT 


->  The  number  of  parameters  in  the  model,  including  both  those  held 
fixed  at  their  starting  values  and  those  which  are  to  be 
estimated. 


— The  number  of  parameters  actually  estimated,  i.e.,  the  number  of 
zero  elements  in  IFIXED.  N.B.  This  value  is  returned  by  the 

estimation  subroutines. 

- > The  argument  controlling  printed  output. 


For  the  estimation  subroutines: 


NPRT  is  a five-digit  integer,  in  which  the  value  of 
digit  (counting  from  left  to  right)  is  used  to  control 
section  of  the  output. 


the  Ith 
the  Ith 


If  the  I1-*1  digit  = 0 the  output  from  the  section  is 

suppressed; 

= 1 the  brief  form  of  the  Ic^  section  is  given; 
> 2 the  full  form  of  the  1**^  section  is  given. 


The  default  value  for  NPRT  is  11112.  When  NPRT  < -1 , or  when 
NPRT  is  not  an  argument  in  the  subroutine  CALL  statement,  the 
default  value  will  be  used.  If  the  convergence  criteria  are  not 
satisfied  the  subroutine  gives  a suitable  warning  and  provides  a 
printed  report  even  if  NPRT  =0.  A full  discussion  of  the 
printed  output  is  given  in  §E.2.a  and  is  summarized  as  follows. 


Section  1 lists  the  starting  estimates  and  control  values. 

Brief  output  and  full  output  are  the  same  for  this 
section. 

Section  2 reports  the  results  of  the  iterations.  Brief  output 
includes  information  only  about  the  first  and  last 
iteration  while  full  output  includes  information  about 
all  of  the  iterations. 

Section  3 provides  information  for  each  observation  based  on  the 
final  solution.  Brief  output  includes  information  for 
the  first  40  observations  while  full  output  provides 
the  information  for  all  of  the  data. 

Section  4 is  a set  of  four  residual  plots.  Brief  output  and 
full  output  are  the  same  for  this  section. 

Section  5 is  the  final  summary  of  the  estimated  parameters. 

Brief  output  does  not  include  printing  the 
variance-covariance  matrix  while  full  output  does. 


For  the  step  size  selection  and  derivative  checking  subroutines: 


If  NPRT  = 0 the  printed  output  is  suppressed. 

If  NPRT  ^ 0 the  printed  output  is  provided. 

— continued — 
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When  the  acceptance  criteria  are  not  met  a printed  report  is 
provided  even  if  NPRT  = 0. 

NROW  • — > The  row  of  the  independent  variable  matrix  at  which  the 

user-supplied  derivative  code  is  to  be  checked.  The  default  value 
is  the  first  row  with  no  independent  variables  equal  to  zero;  when 
all  rows  have  one  or  more  independent  variables  equal  to  zero,  row 
one  will  be  used  for  the  default  value.  When  the  user-supplied 
value  is  outside  the  range  [1,  N]  or  when  NROW  is  not  an  argument 
of  the  subroutine  CALL  statement  the  default  value  will  be  used. 

NTAU  — •>  The  agreement  tolerance,  i.e.,  the  number  of  digits  of  agreement 

required  between  the  user-supplied  derivatives  and  the  derivatives 
numerically  approximated  by  the  derivative  checking  subroutine. 
The  default  value  is  NETA/4.  When  the  user-supplied  value  of  NTAU 
is  outside  the  range  [1,  NETA/2]  or  when  NTAU  is  not  an  argument 
of  the  subroutine  CALL  statement  the  default  value  will  be  used. 

PAR  — The  vector  of  dimension  at  least  NPAR  that  contains  the  parameter 
values.  For  all  estimation  subroutines  it  must  contain  initial 
values  for  the  parameters  on  input  and  will  contain  the  final 
values  on  return.  For  the  step  size  and  derivative  checking 
subroutines  it  must  contain  the  parameter  values  at  which  the 
operations  are  to  be  performed. 

P V <—  The  vector  of  dimension  at  least  N that  contains  the  predicted 

values  of  the  dependent  variable  at  the  solution, 

a <*. 

PV  (i ) = f^x-pB)  = y±  for  i = 1,  N. 

RES  <—  The  vector  of  dimension  at  least  N that  contains  the  residuals  at 
the  solution, 

/*>  a * 

RES(i)  = y (i ) - f 1(xi , 3 ) = y(i)  - y(i)  = e(i)  for  i = 1,  N, 

RSD  <—  The  residual  standard  deviation  at  the  solution, 

* 

RSD  - (RSS(8)/(NNZW-NPARE))1/2  . 

SCALE  -->  The  vector  of  dimension  at  least  NPAR  that  contains  the  scale,  or 
typical  size,  of  each  parameter.  The  vector  SCALE  is  used  to 
normalize  the  size  of  each  parameter  so  that 

1 8j£  (j  ) / SCALE(  j ) | » |8£(k)/SCALE(k)|  for  k = 1,  ...,  NPAR 

and  j = 1 , . . . , NPAR. 

Values  of  |sCALE(k)|  > | 8^ (k ) | can  be  used  to  increase  the  step 
size  in  cases  where  the  model  function  is  known  to  be  insensitive 
to  small  changes  in  the  value  B^C^). 

— continued — 
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For  the  estimation  subroutines: 


The  default  values  for  SCALE  are  selected  by  the  NL2S0L 
algorithm  [Dennis  et  al.  1981a  and  1981b]  and  are  updated  at 
each  iteration.  When  SCALE  is  not  an  argument  in  the  subroutine 
CALL  statement  or  when  the  user-supplied  value  for  SCALE(l)  <0 
the  default  procedure  will  be  used  to  select  scale  values.  When 
SCALE (1 ) > 0,  values  of  SCALE (k)  < 0 for  k = 2,  NPAR  will 

be  interpreted  as  an  input  error.  User-supplied  scale  values 
may  be  either  a vector  of  the  typical  size  of  each  parameter  or 
a vector  of  ones  if  the  typical  sizes  of  the  parameters  are 
roughly  equal;  user-supplied  scale  values  can  sometimes  result 
in  reduced  computing  time  since  these  values  are  not  updated  at 
each  iteration. 

For  the  derivative  checking  and  step  size  selection  subroutines: 
The  default  values  of  SCALE  are  defined  as: 

SCALE(k)  = 1.0  if  PAR(k)  = 0.0  , 

} for  k = 1,  ...,  NPAR. 

SCALE(k)  = j PAR(k) | otherwise 

When  SCALE  is  not  an  argument  in  the  subroutine  CALL  statement 
or  when  the  user-supplied  value  of  |SGALE(k)|  < | PAR ( k ) | the 

default  value  for  SCALE(k)  is  used.  When  SCALE(l)  < 0,  the 

default  values  will  be  used  for  SCALE(k),  k = 1,  ...,  NPAR. 
When  SCALE (1 ) > 0,  values  of  SCALE (k)  <0  for  k = 2,  ...,  NPAR 
will  be  interpreted  as  an  input  error. 

SDPV  <“-  The  vector  of  dimension  at  least  N that  contains  an  approximation 
to  the  standard  deviation  of  each  predicted  value  at  the 
solution, 

Ab  A 

SDPV(i)  = the  ic^  diagonal  element  of  [ (D® VCV» DT)] 1 /2 

for  i = 1,  ...,  N.  This  approximation  is  based  on  a linearization 
of  the  model  in  the  neighborhood  of  the  solution;  the  validity  of 
the  approximation  depends  on  the  nonlinearity  of  the  model.  This 
approximation  may  be  extremely  inaccurate  for  a problem  with  a 
highly  nonlinear  model. 

SDRES  <--  The  vector  of  dimension  at  least  N that  contains  an  approximation 
to  the  standardized  residuals  at  the  solution, 

SDRES (i ) = RES(i ) /[ ( RSD2 /WT(i ) ) - SDPV(i)2]1/2 

for  i = l,  . N,  which  is  the  it^1  residual  divided  by  its 
individual  estimated  standard  deviation.  This  approximation  is 
based  on  a linearization  of  the  model  in  the  neighborhood  of  the 
solution;  the  validity  of  the  approximation  depends  on  the 
nonlinearity  of  the  model.  This  approximation  may  be  extremely 
inaccurate  for  a problem  with  a highly  nonlinear  model. 
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STOPP 


— > 


The  stopping  value  for  the  convergence  test  based  on  the  maximum 
scaled  relative  change  in  the  parameters  at  the  most  recent 
iteration.  The  convergence  criterion  is  satisfied  if  the  current 
step  is  a Newton  step  and 


maxf  [ Bo  4-]  (k)-B^  (k)  1 /SCALE(k)  for  k - 1,  . ..,  NPAR}  gTOPP 
max{(  | +| B^ (k) | ) /SCALE  (k)  for  k =1,  ...,  NPAR} 

[See  Dennis  et  al.  1981a. J This  convergence  test  is  roughly 
equivalent  to  the  test  based  on  the  maximum  relative  change  in 
each  parameter  as  measured  by  max{  | B^+i  (k)-B^  (k)  | / | (k)  | for  k = 
1,  ...,  NPAR} . STOPP  is  not  a scale-dependent  value;  if  its  value 
is  10”4  then  this  criteria  will  be  met  when  the  first  four  digits 
of  each  parameter  are  the  same  at  two  successive  iterations 
regardless  of  the  size  of  the  parameter  values. 

The  default  value  is  approximately  iq“BIGITS/2 ^ where  DIGITS  is 
the  number  of  decimal  digits  carried  by  the  user's  computer  for  a 
single  precision  value  when  the  single  precision  version  of 
ST ARP AC  is  being  used  and  is  the  number  carried  for  a double 
precision  value  otherwise.  When  the  user-supplied  value  for  STOPP 
is  outside  the  interval  [0.0,  1.0]  or  when  STOPP  is  not  an 
argument  of  the  subroutine  CALL  statement  the  default  value  will 
be  used. 


STOPSS  — > The  stopping  value  for  the  convergence  test  based  on  the  ratio  of 
the  forecasted  change  in  the  residual  sum  of  squares,  ARSS^+j,  to 
the  current  residual  sum  of  squares,  RSSCB^).  The  convergence 
criterion  is  satisfied  if  certain  conditions  are  met  and 

ARSS£+1/RSS(3£)  < STOPSS. 

[See  Dennis  et  al.  1981a. ] This  convergence  test  is  roughly 
equivalent  to  the  test  based  on  the  relative  change  in  the 
residual  standard  deviation  between  two  iterations  l and  £+1  as 
measured  by  (s^  - s£+i)/s£*  STOPSS  is  not  a scale-dependent 
value;  if  its  value  is  10~5  this  criteria  will  be  met  when  the 
first  five  digits  of  the  residual  sum  of  squares  are  the  same  at 
two  successive  iterations  regardless  of  the  size  of  the  residual 
sum  of  squares. 

The  default  value  is  approximately  the  maximum  of  10-^  and 
10-2. DIGITS/3,  where  DIGITS  is  the  number  of  decimal  digits 
carried  by  the  user's  computer  for  a single  precision  value  when 
the  single  precision  version  of  STARPAC  is  being  used  and  is  the 
number  carried  for  a double  precision  value  otherwise.  When  the 
user-supplied  value  for  STOPSS  is  outside  the  interval 
[10  S,  o.l]  or  when  STOPSS  is  not  an  argument  of  the 

subroutine  CALL  statement  the  default  value  will  be  used. 
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STP  The  vector  of  dimension  at  least  NPAR  that  contains  the  relative 

step  sizes  used  to  approximate  the  derivative  matrix  numerically. 
It  is  input  to  the  estimation  subroutines  and  returned  from  the 
step  size  selection  subroutines.  The  procedure  used  to  select  the 
default  values  is  described  in  §E.l»b.  For  the  estimation 
subroutines,  when  STP  is  not  an  argument  of  the  subroutine  CALL 
statement  or  when  STP(l)  < 0 the  default  values  will  be  used  for 
all  of  the  step  sizes,  and  when.STP(l)  > 0 values  of  STP(k)  < 0 
for  k = 2,  ...,  NPAR  will  be  interpreted  as  an  input  error. 

VCV  < — - The  matrix  of  dimension  at  least  NPARE  by  NPARE  that  contains  the 

variance-covariance  matrix  of  the  estimated  parameters,  approxima- 
ted as  designated  by  argument  IVAPRX.  The  parameters  which  are 
held  fixed  [see  argument  IFIXED]  are  not  included  in  the  variance- 
covariance  matrix. 

The  approximation  of  the  variance-covariance  matrix  is  based  on  a 
linearization  of  the  model  in  the  neighborhood  of  the  solution; 
the  validity  of  the  approximation  depends  on  the  nonlinearity  of 
the  model.  This  approximation  may  be  extremely  inaccurate  for  a 
problem  with  a highly  nonlinear  model. 

WT  -->  xhe  vector  of  dimension  at  least  N that  contains  the  weights. 

Negative  weights  are  not  allowed  and  the  number  of  nonzero  weights 
must  equal  or  exceed  the  number  of  parameters  being  estimated.  A 
zero  weight  eliminates  the  corresponding  observation  from  the 
analysis,  although  the  residual,  the  predicted  value  and  the 
standard  deviation  of  the  predicted  value  are  still  computed. 
[See  Appendix  B.] 

XM  — > The  matrix  of  dimension  at  least  N by  M whose  j*-*1  column  contains 

the  N values  of  the  j1-*1  independent  variable,  j = 1,  ...,  M. 

Y ~- > The  vector  of  dimension  at  least  N that  contains  the  dependent 

variable. 


E . Computational  Methods 
E . 1 Algorithms 

E.l.a  Nonlinear  Least  Squares  Estimation 

The  nonlinear  least  squares  estimation  subroutines  use  the  NL2S0L 
software  package  written  by  Dennis  et  al.  [1981a  and  1981b].  The  observations 
of  the  dependent  variable,  which  are  measured  with  error,  are  iteratively  fit 
to  a nonlinear  model  by  minimizing  the  sums  of  squares  of  the  errors  as 
described  in  §A.  The  iterations  continue  until  the  convergence  criteria  based 
on  the  change  in  the  parameter  values  or  in  the  residual  sum  of  squares  are 
satisfied  [see  §D,  arguments  STOPP  and  STOPSS],  the  maximum  number  of 
iterations  (or  model  subroutine  calls)  is  reached  [see  §D,  argument  MIT],  or 
the  iterations  are  terminated  due  to  singularity  in  the  model  or  false 
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convergence.  All  but  the  first  of  these  stopping  conditions  may  indicate 
computational  problems  and  will  produce  an  error  report.  [See  chapter  1, 
§D. 5.  ] 


Singular  convergence  means  that  the  model  contains  too  many  parameters, 
at  least  near  the  solution,  while  false  convergence  can  indicate  that  either 
STOPSS  or  STOPP  is  set  too  small  for  the  accuracy  to  which  the  model  and  its 
derivatives  are  being  computed  or  that  there- is  an  error  or  discontinuity  in 
the  derivative.  Users  should  examine  their  models  to  determine  and  correct 
the  underlying  cause  of  singular  or  false  convergence. 

Iterative  procedures  for  solving  nonlinear  least  squares  problems  are 
discussed  in  Dennis  and  Schnabel  [1983] , Draper  and  Smith  [1981]  and  Kennedy 
and  Gentle  [1980].  The  specific  procedure  used  in  STARPAC  is  as  follows.  At 
iteration  £+1  the  values  of  the  parameter  vector  8^+1  are  given  by 

&£  + 1 = &£  “ (D£T*W,D£  + S£  + A£)~1*D£T*W*££T 
subject  to  the  restriction  that 
NPAR 

{ I [(S*+lOO  “ 6£(k))/SCALE(k)]2}l/2  < , 

k=l 


the  vector  of  NPAR  estimated  parameter  values  from  the  £ 
iteration. 

D£  is  the  N by  NPAR  matrix  of  the  partial  derivatives, 

D£(i»k)  = 9 f i(xi ,6^ )/38^ (k)  for  i = 1,  ...,  N and  k = 1,  . . . , NPAR. 

W is  an  N by  N diagonal  matrix  of  user-supplied  weights, 

W = diag{  wt-^ » i = 1,  ...»  N}  , 

when  a weighted  analysis  is  performed  and  is  the  identity  matrix 
otherwise. 

S^  is  an  approximation  to  the  exact  term  S^*  in  the  matrix  of  second 

order  terms  (Hessian)  of  the  Taylor  series  expansion  of  the  residual 
sum  of  squares  function, 

N 

S£  * ( j » k ) = l [e£i,wti-(92e£(i)/90£  (j)984(k>)  ] , 
i=l 

for  j = 1,  ...,  NPAR  and  k = 1,  ...,  NPAR. 

is  the  vector  of  the  N residuals  from  the  previous  iteration. 


where 
$£  is 
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6^  is  the  adaptively  chosen  diameter  of  the  trust  region,  i.e.,  the 

region  in  which  the  local  approximation  to  the  user's  model  function 
is  reliable.  At  each  iteration  l , 6^  is  computed  based  on  information 
from  the  previous  iteration.  At  the  first  iteration,  the  initial 
value,  6q,  is  supplied  by  argument  DELTA  which  can  be  used  to  control 
the  change  in  the  parameters  permitted  at  the  first  iteration. 

is  an  NPAR  by  NPAR  diagonal  matrix, 

A = diagj A^ /SCALE(k) , k = 1,  ...,  NPAR}  , 

where  A^  is  chosen  to  approximate  the  smallest  non-negative  number 
such  that  the  restriction  given  above  on  the  size  of  the  change  in  the 
parameters  is  satisfied. 

The  second  order  term  $£  , which  is  expensive  and  difficult  to  compute 
accurately,  is  important  only  if  it  is  large  compared  to  the  term  D£T*W®D£, 
that  is,  when  the  residuals  are  large  or  the  model  is  highly  nonlinear.  When 
S^*  is  large  compared  to  D£T«W®D£,  algorithms  which  ignore  it,  such  as 
Levenberg-Marquardt  or  Gauss-Newton,  may  converge  slowly.  The  NL2S0L 
algorithm  used  by  STARPAC,  however,  adaptively  decides  when  inclusion  of  this 
term  is  necessary  for  reliable  results  and  uses  an  inexpensive  approximation 
to  in  those  cases. 

The  matrix,  D,  of  partial  derivatives  of  the  model  with  respect  to  each 
parameter  is  either  computed  analytically  using  a user-supplied  subroutine, 
NLSDRV , or  is  numerically  approximated  using  forward  difference  quotients  as 
described  in  §E.l.b.  When  the  derivatives  are  approximated  numerically,  the 
least  squares  solution,  especially  the  variance-covariance  matrix,  can  be 
sensitive  to  the  step  sizes  used  for  the  approximation.  The  user  may  want  to 
use  STARPAC  subroutines  STPLS  or  STPLSC  to  recompute  the  step  sizes  at  the 
solution  provided  by  the  estimation  subroutines  to  assure  that  the  step  sizes 
which  were  used  are  still  acceptable.  If  there  is  a significant  change  in  the 

step  size  the  least  squares  solution  should  be  recomputed  with  the  new  step 

sizes  from  the  current  point.  In  addition,  if  the  estimation  subroutine  has 
convergence  problems  the  user  may  want  to  recompute  the  step  sizes  with  the 
most  recent  parameter  values  to  see  if  a change  in  the  curvature  of  the  model, 

which  will  be  reflected  as  a change  in  the  optimum  step  sizes,  is  causing  the 

problem. 

Dennis  et  al.  [1981a]  provides  a detailed  description  of  the  algorithm 
used  in  STARPAC.  STARPAC  also  includes  the  subroutines  NL2S0L,  NL2SN0,  and 
NL2ITR,  which  they  reference,  and  which  can  be  used  as  documented  by  them. 
[See  Dennis  et  al.  1981b.] 


E.l.b  Derivative  Step  Size  Selection 

The  STARPAC  step  size  selection  subroutines  use  an  algorithm  developed  by 
Schnabel  [1982]  to  compute  optimum  step  sizes  for  approximating  the  partial 
derivatives  of  the  model  with  respect  to  each  parameter.  Briefly,  the 
relative  step  sizes  selected  by  these  subroutines  are  those  which  produce 


9-22 


forward  difference  quotient  approximations  to  the  derivative,  D^,  that  agree 
reasonably  well  with  the  central  difference  quotient  approximations,  Dccj»  The 
central  difference  quotient  approximations  are  twice  as  accurate  but  also 
twice  as  expensive  to  compute.  Since  the  additional  accuracy  is  not  usually 
needed,  central  difference  quotient  approximations  are  not  used  by  the 
estimation  subroutines. 

The  number  of  reliable  digits  in  these  derivatives  is  a function  of  the 
step  sizes  used  to  compute  them.  Given  properly  chosen  step  sizes,  the  number 
of  reliable  digits  in  Dfd  and  Dcd  will  be  approximately  n /2  and  n, 
respectively,  where  q is  the  number  of  reliable  digits  in  the  predicted 
values,  PV,  from  the  user's  model  subroutine.  For  example,  if  the  predicted 
values  are  computed  using  an  iterative  procedure  (such  as  quadrature  or  a 
solution  of  partial  differential  equations)  which  is  expected  to  provide  five 
good  digits,  then  q would  be  five;  if  the  predicted  values  are  calculated  from 
a simple  algebraic  expression  translated  directly  into  Fortran  code,  then  q 
would  (usually)  be  the  number  of  decimal  digits  carried  by  the  user's  computer 
for  the  results. 

The  relative  step  size  for  8(k),  k = 1,  NPAR,  is  initially 

STP(k)  = 2(10"NETA/y)1/2  for  k = 1,  NPAR, 

where 

Y is  the  average  curvature  (estimated  by  STARPAC)  of  the  model  with 

respect  to  8 (k) . 

The  forward  difference  quotient  approximations  with  respect  to  8(k), 
k = 1 , . . . , NPAR  are  then 

f1(xi,0k)  - fi(xi,$) 

Df(j(i,k)  = for  i = 1,  ...,  N, 

STP(k)«  SCALE (k)»  SIGN(g (k) ) 

where 

is  the  function  which  models  the  i*-*1  observation. 

is  the  vector  of  the  values  of  the  M independent  variables  at  the  itk 
observation. 

8 is  the  vector  of  the  NPAR  parameter  values. 

8 k is  a vector  which  has  the  same  values  as  8 except  that  the  k^1 

parameter  is  equal  to 

8 (k)  + ( STP(k)»  SCALE (k)»  SIGN(8 (k) )) . 

SIGN  is  a function  which  returns  the  sign  of  its  argument. 
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The  central  difference  approximations  to  the  model  derivative  with 
respect  to  B(k),  k = 1,  NPAR,  are 

fi(xi,B+k)  - f^x^S-1*) 

DC(J(i,k)  = for  i = 1,  ...,  N, 

31/3. 10~NETA/3.SCALE(k)*SIGN(B(k)) 


where 

B +k  is  a vector  which  has  the  same  values  as  B except  that  the  ktE 

parameter  is  equal  to 

B (k)  + (31/3«  10_NETA/3.SCALE(k)«SIGN(B(k)))  . 

B is  a vector  which  has  the  same  values  as  B except  that  the  ktn 

parameter  is  equal  to 

B (k)  - ( 31/3« 10"NETA/3.SCALE(k)*SIGN(B(k))) . 

The  relative  step  size  is  considered  acceptable  if,  for  at  least  N-a 
observations , 

|Dfd(i,k)  - Dcd(i,k)|  < min( 10“NETA/^ s 10"2}  for  i = 1,  . N, 

where  a is  the  number  of  observations  exempted  from  meeting  the  above 
acceptance  criterion.  [See  §D,  argument  EXMPT.]  If  the  step  size  is  not 

acceptable,  it  is  adjusted  by  factors  of  10  until  the  condition  is  met  or 
until  no  further  decrease  in  the  number  of  failures  can  be  made,  although  in 
no  case  will  the  selected  relative  step  size  be  greater  than  1.0  or  less  than 
10“NETA 

Note  that  the  step  size  selection  subroutines  will  return  the  selected 
step  sizes  even  when  the  number  of  failures  exceeds  the  allowed  value;  this 
condition  will  be  noted  by  the  value  of  IERR.  The  detailed  printed  output 
should  always  be  examined  for  problems  discovered  by  the  step  size  selection 
subroutines. 


E.l.c  Derivative  Checking 

The  STARPAC  derivative  checking  subroutines  use  an  algorithm  developed  by 
Schnabel  [1982]  to  determine  the  validity  of  the  user-supplied  derivative 
subroutine.  The  user-supplied  derivative  subroutine  is  considered  correct  for 
a given  row  i,  i = 1,  ...,  N,  and  coefficient  B (k),  k = 1,  ...,  NPAR,  if 

|Dfd(i,k)  - D(i , k) | < 10“T  |D(i,k)| 


where 

D is  the  derivative  computed  by  the  user’s  subroutine. 
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Df^  is  the  forward  difference  quotient  approximation  to  the  derivative 

described  in  §E.l.b. 

x is  the  agreement  tolerance,  i.e. , number  of  digits  of  agreement 

required  between  D and  Df^,  which  must  be  less  than  or  equal  to  the 
number  of  good  digits  in  Df^.  [See  §D,  argument  NTAU. ] 

When  the  agreement  tolerance  is  not  satisfied  the  checking  subroutine 
attempts  to  determine  whether  the  disagreement  is  due  to  an  error  in  the 
user's  code  or  is  due  to  the  inaccuracy  of  the  difference  quotient  approxima- 
tion, caused  either  by  high  curvature  in  the  user's  model  or  by  significant 
roundoff  error. 

The  derivative  checking  subroutines  each  check  only  one  row  of  the 
derivative  matrix.  The  user  should  examine  the  row  at  which  the  derivatives 
were  checked  to  ensure  that  some  relation  between  the  parameters  and 
independent  variables,  such  as  a zero-valued  independent  variable  or  a factor 
(x^  “ 8(k))  when  x^  = 8(k),  is  not  hiding  the  effect  of  an  incorrectly 
computed  derivative.  Checking  only  one  row  is  appropriate  since  the  same  code 
is  frequently  used  to  compute  the  model  function  and  derivatives  at  each  row 
1 = 1,  . . . , N,  as  is  the  case  in  the  examples  shown  in  §F.  If  the  code  used 
to  express  the  model  function  and  derivatives  is  not  the  same  for  each  row, 
then  each  distinct  section  of  the  code  should  be  checked  by  making  multiple 
calls  to  DCKLSC  with  argument  NROW  set  to  a row  within  each  section. 


E . 2 Computed  Results  and  Printed  Output 

E.2.a  The  Nonlinear  Least  Squares  Estimation  Subroutines 

The  argument  controlling  the  printed  output,  NPRT,  is  discussed  in  §D. 

The  output  from  the  nonlinear  least  squares  estimation  subroutines 
consists  of  five  sections,  several  of  which  include  tables  summarizing  the 
results.  In  the  following  descriptions  the  actual  table  headings  are  given  by 
the  underlined,  uppercase  phrases.  Results  which  correspond  to  input  or 
returned  subroutine  CALL  statement  arguments  are  identified  by  the  argument 
name  in  uppercase  (not  underlined). 

Section  1 provides  a summary  of  the  initial  estimates  and  control  values.  It 
lists  the  following  information. 

• The  initial  values  of  the  parameters,  PAR,  and  whether  they  are  to  be 
held  fixed  or  not,  IFIXED. 

• The  scale  values,  SCALE. 

• Either  the  step  sizes  used  to  approximate  the  derivatives  numerically, 
or,  when  user-supplied  (analytic)  derivatives  are  used,  the  results  of 
the  checking  procedure;  and  the  control  values  used  in  these  computa- 
tions as  applicable.  [See  §E.l.b  and  §E.l.c.] 
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• The  number  of  observations,  N. 

• The  number  of  observations  with  nonzero  weights,  NNZW. 

• The  number  of  independent  variables,  M. 

• The  maximum  number  of  iterations  allowed,  MIT. 

o The  maximum  number  of  model  subroutine  calls  allowed. 

• The  two  convergence  criteria,  STOPSS  and  STOPP. 

• The  maximum  change  in  the  parameters  allowed  at  the  first  iteration, 
DELTA. 

• The  residual  sum  of  squares  computed  using  the  starting  parameter 
values. 

• The  residual  standard  deviation,  RSD,  computed  using  the  starting 
parameter  values. 

Section  2 lists  selected  information  about  each  iteration  and  includes  the 
reason  the  iterations  were  terminated.  The  information  provided  for 
each  iteration  includes  the  following. 

• The  iteration  number. 

• MODEL  CALLS:  the  total  number  of  times  since  execution  began  that  the 
user’s  model  subroutine  has  been  called,  not  including  calls  required 
to  approximate  the  derivatives  numerically. 

® RSD;  the  residual  standard  deviation  computed  using  the  parameter 
values  from  the  current  iteration. 

• RSS : the  residual  sum  of  squares  computed  using  the  parameter  values 

from  the  current  iteration. 

• REL  CHNG  RSS:  the  relative  change  in  the  residual  sum  of  squares 

caused  by  the  current  iteration. 

• FORECASTED  REL  CHNG  RSS:  the  forecasted  relative  change  in  the 

residual  sum  of  squares  at  the  current  iteration,  and  whether  this 
value  was  checked  against  STOPSS  (CHKD  = Y)  or  not  (CHKD  = N). 

• REL  CHNG  PAR:  the  maximum  scaled  relative  change  in  the  parameters  at 

the  current  iteration,  and  whether  this  value  was  checked  against 
STOPP  (CHKD  = Y)  or  not  (CHKD  = N). 

• CURRENT  PARAMETER  VALUES:  the  estimated  parameter  values  resulting 

from  the  current  iteration. 
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Section  3 provides  the  following  information  for  each  observation,  i = 1, 

N,  based  on  the  final  solution. 

• ROW ♦ the  row  number  of  the  observations. 

• PREDICTOR  VALUES:  the  values  for  up  to  the  first  three  columns  of  the 

independent  variable  matrix,  XM,  not  including  the  first  column  if  it 
is  constant. 

• DEPENDENT  VARIABLE:  the  values  of  the  dependent  variable,  Y. 

• PREDICTED  VALUE:  the  estimated  predicted  values,  PV,  from  the  fit. 

• STD  DEV  OF  PREP  VALUE:  the  standard  deviations  of  the  predicted 

values,  SDPV. 

• RESIDUAL : the  error  estimates,  RES. 

• STD  RES:  the  standardized  residuals,  SDRES. 

® WEIGHT;  the  user-supplied  weights,  WT,  printed  only  when  weighted 

analysis  is  performed. 

Section  4 displays  the  following  plots  of  the  standardized  residuals. 

• The  standardized  residuals  versus  row  numbers. 

• The  standardized  residuals  versus  predicted  values. 

• The  autocorrelation  function  of  the  (non-standardized)  residuals. 

• The  normal  probability  plot  of  the  standardized  residuals. 

Section  5 summarizes  the  following  information  about  the  final  parameter 
estimates  and  their  variances. 

• The  variance-covariance  matrix,  VCV,  of  the  estimated  (unfixed) 
parameters,  and  the  corresponding  correlation  matrix, 

r jk  = VCV(j,k)/(VCV(j,j)  VCV(k,k))1/2  f or  ,j  = 1 , ...,  NPARE 

and  k = 1,  ...,  NPARE. 

• PARAMETER:  the  final  value  of  each  parameter,  PAR(k),  k = 1,  ..., 

NPAR. 

• SD  OF  PAR:  the  standard  deviation  of  each  estimated  parameter, 

( VCV(k,k))1/2  for  k = 1,  ...,  NPAR. 

• RATIO:  the  ratio  of  each  estimated  parameter  to  its  standard 

deviation, 

RAT I Ok  = PAR(k)/(VCV(k,k))1/2  for  k = 1,  ...,  NPAR. 
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• APPROXIMATE  95-PERCENT  CONFIDENCE  LIMITS:  the  lower  and  upper 

95-percent  confidence  limits  for  each  parameter,  computed  using  the 
appropriate  value  of  the  Student's  t distribution  with  NNZW-NPARE 
degrees  of  freedom. 

o the  residual  sum  of  squares,  RSS(B). 

• the  residual  standard  deviation  at  the  solution,  RSD. 

o the  residual  degrees  of  freedom,  NNZW-NPARE. 

® an  approximation  to  the  condition  number  of  the  derivative  matrix,  D 
(the  Jacobian),  under  the  assumption  that  the  absolute  error  in  each 
column  of  D is  roughly  equal.  The  approximation  will  be  meaningless 

if  this  assumption  is  not  valid;  otherwise  it  will  usually 

underestimate  the  actual  condition  number  by  a factor  of  from  2 to  10. 
[See  Dongarra  et  al.  1979,  p.  9.5.] 

NOTE;  The  standard  deviation  of  the  predicted  values,  the  standardized 
residuals,  the  variance-covariance  matrix,  the  standard  deviations  of  the 
parameters  and  the  95-percent  confidence  limits  on  the  parameters  are  all 
based  on  a linear  approximation  to  the  model  in  a neighborhood  of  the 
solution;  the  validity  of  this  approximation  depends  on  the  nonlinearity  of 
the  model.  The  statistics  based  on  this  approximation  may  be  extremely 
inaccurate  for  a problem  with  a highly  nonlinear  model. 


E.2.b  The  Derivative  Step  Size  Selection  Subroutines 

The  argument  controlling  the  printed  output,  NPRT,  is  discussed  in  §D. 

The  output  from  the  step  size  selection  subroutines  consists  of  a summary 
of  the  input  and  control  values  and,  for  each  parameter,  the  selected  relative 
step  size,  the  number  of  observations  at  which  this  step  size  failed  the  step 
size  selection  criteria  and  the  row  numbers  at  which  the  failures  occurred. 


E . 2 . c The  Derivative  Checking  Subroutines 

The  argument  controlling  the  printed  output,  NPRT,  is  discussed  in  §D. 

The  output  for  the  derivative  checking  subroutines  consists  of  a summary 
of  the  input  and  control  values  and  the  results  of  the  derivative  checking 
test  with  respect  to  each  of  the  model  parameters,  6(k),  k = 1,  ...,  NPAR. 
The  possible  test  results  are: 

OK  - 


® The  user-supplied  derivative  and  the  numerical  derivative  agree  to  the 
required  number  of  digits. 


QUESTIONABLE  - 


o The  user-supplied  derivative  and  the  approximated  derivative  agree  to 
the  required  number  of  digits  but  both  are  equal  to  zero.  The  user 
should  recheck  the  derivative  at  another  row. 

o The  user-supplied  derivative  and  the  approximated  derivative  do  not 
agree  to  the  required  number  of  digits  but  the  user-supplied  deriva- 
tive is  identically  zero  and  the  approximated  derivative  is  nearly 
zero.  The  user  should  recheck  the  derivative  at  another  row. 

© The  user-supplied  derivative  and  the  approximated  derivative  disagree 
but  the  user-supplied  derivative  is  identically  zero.  The  user  should 
recheck  the  derivative  at  another  row. 

® The  user-supplied  derivative  and  the  approximated  derivative  disagree 
but  the  validity  of  the  approximated  derivative  is  questionable 
because  either  the  ratio  of  the  relative  curvature  of  the  model  to  the 
slope  of  the  model  is  too  high  or  SCALE(k)  is  wrong. 

• The  user-supplied  derivative  and  the  approximated  derivative  disagree 
but  the  validity  of  the  estimated  derivative  is  questionable  because 
the  ratio  of  the  relative  curvature  of  the  model  to  the  slope  of  the 
model  is  too  high. 


• The  user-supplied  derivative  and  the  approximated  derivative  disagree, 
and  there  is  no  reason  to  question  the  accuracy  of  the  approximated 
derivative. 


The  sample  programs  of  this  section  use  the  model  and  data  given  in 
example  one,  pages  428  to  441  of  Daniel  and  Wood  [1980];  the  model  is 


Nonlinear  Least  Squares  Estimation.  In  the  example  program  of  figure 
F-la,  NLS  is  used  to  compute  the  least  squares  solution  using  numerically 
approximated  derivatives;  figures  F-lb  through  F-lf  show  the  output  from  NLS. 

In  the  example  program  of  figures  F-2a  and  F-2b,  NLSD  is  used  to  compute 
the  least  squares  solution  given  analytic  derivatives;  figures  F-2c  through 
F-2g  show  the  output  from  NLSD. 


Derivative  Step  Size  Selection.  In  the  example  program  of  figure  F-3a, 
STPLS  is  used  to  compute  the  optimum  step  sizes  for  numerically  approximating 
the  derivatives  with  respect  to  each  of  the  parameters,  0(k),  k = 1,  2. 
Figure  F-3b  shows  the  output  from  STPLS. 


INCORRECT  - 


F 


f-[(x£,0)  - 0 ( 1 ) »x^(  1 (2)  for  i = i 


N 
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Derivative  Checking.  In  the  example  program  of  figures  F-4a  and  F-4b, 
DCKLS  is  used  to  check  the  validity  of  a user-supplied,  derivative  subroutine. 
In  figure  F-4b,  the  derivative  subroutine  has  been  intentionally  coded 
incorrectly  in  order  to  display  the  report  obtained  when  the  derivative 
checking  subroutine  determines  the  derivatives  are  incorrect,  and  the  starting 
parameter  values  have  been  chosen  in  order  to  display  the  report  obtained  when 
the  test  results  are  questionable.  Figure  F-4c  shows  the  output  from  DCKLS. 
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Nonlinear  Least  Squares  Estimation 
With  Numerically  Approximated  Derivatives 


MAIN  PROGRAM! 


MODEL  SUBROUTINE « 


PROGRAM  EXANPl 
C 

C DEMONSTRATE  NLS  USING  SINGLE  PRECISION  VERSION  OF  STARPaC 

C RUN  ON  CYBER  180/8*0. 

C 

C OUTPUT  UNIT  IS  6 (AUTOMATICALLY  EQUATED  TO  FILE  TAPE6  ON  CYRIRS) 

C CSEE  CHAPTER  1 * SECTION  D.4J 

C 

C N.B.  DECLARATION  OF  Y*  XM*  PAR  AND  RES  MUST  BE  CHANGED  TO  DOUBLE  PRECISION 

C IF  DOUBLE  PRECISION  VERSION  OF  STARPAC  IS  USEO. 

C 

REAL  Y ( 10 ) * XM ( 10*  9 ) * PAR ( 5 ) * RES(IO) 

DOUBLE  PRECISION  DSTAM200) 

C 

EXTERNAL  NLSMDL 

C 

COMMON  /CSTAK/  DSTAK 

C 

C SPECIFY  NECESSARY  DIMENSIONS 

C 

LOST  AM  ■ 200 
IXM  « 10 
C 

C READ  NUMBER  OF  PARAMETERS 

C STARTING  VALUES  FOR  PARAMETERS 

C NUMBER  OF  OBSERVATIONS  AND  NUMBER  OF  INDEPENDENT  VARIABLES 

C INDEPENDENT  AND  DEPENDENT  VARIABLES 

C 

READ  100*  NPAR 

READ  101*  ( P AR ( I ) * I»1,NPAR» 

READ  100*  N*  H 

READ  101#  ( (XM(I*J8»  I-1#N>»  J-lsMI*  (YCII*  I«1*N» 

C 

C PRINT  TITLE  AND  CALL  NLS  TO  PERFORM  NONLINEAR  REGRESSION 

C KITH  NUMERICALLY  APPROXIMATED  DERIVATIVES 

C 

WRITE  (6,  102  J 

CALL  NLS  <T*  XM#  N»  M*  IXM#  NLSMDL*  PAR*  NPAR*  RES#  LDSTAKJ 

C 

STOP 

C 

C FORMAT  STATEMENTS 

C 

100  FORMAT  <2198 

101  FORMAT  (6F6.38 

102  FORMAT  P1RESULTS  OF  STARPAC'* 

* « NONLINEAR  LEAST  SOUARES  SUBROUTINE  NLS») 

END 

SUBROUTINE  NLSMDL  (PAR,  NPAR#  XM*  N«  M,  IXM*  PV8 
C 

C SUBROUTINE  TO  COMPUTE  PREDICTED  VALUES  OF  DEPENDENT  VARIABLE 
C 

C N.B.  DECLARATION  OF  PAR*  XM  AND  PV  MUST  BE  CHAN6ED  TO  DOUBLE  PRECISION 

C IF  DOUBLE  PRECISION  VERSION  OF  STARPAC  IS  USED. 

C 

REAL  P AR ( NP AR  8 » XM(XXN,M8»  PV(N8 

C 

DO  10  I - 1*  N 

PVU)  - PAR(l)  * XM  ( I * 1)  **  PAR(28 
10  CONTINUE 

C 

RETURN 

END 


2 

0.729  4.000 
6 1 
1.309  1.471 
2.138  3.421 


1.490  1.969  1.611 
3.997  4.340  4.882 


1.680 

9.660 


Figure  F-la 


Example  program  using  NLS 
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RESULTS  OF  STARPAC  NONLINEAR  LEAST  SQUARES  SUBROUTINE  NIS 
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RESIDUAL  STANDARD  DEVIATION  FOR  INPUT  PARAMETER  VALUES  IRSDI  „6067E-0i 
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Example  of  NLS  output  (continued) 


RE  SUITS  FROM  1EAST  SQUARES  FIT 


in 


<x>  m ^ o o 

«r  <\i  <\l  35 


I fvi  . 


fVJ  • 


o o o o o o 
1(11(1 
Ui  UJ  UJ  UJ  U»  U£ 
<H  # O N ^ 
a m fi  fn  o j> 
^ CO  **  ® ^ «# 

^ o n -o 
r»®  ® cr  m 
*>  en  m ^ oo 

£ 93  N W <0  O 
ff*5  O*  ^5  9** 

e r 


» <€ 
uj  » 
© 


0 o © o © © 

1 e i i i e 

UJ  UJ  ID  tafc)  W)  ULI 
9D 

^ CD  ftJ  c-0  e°4  fSJ 

o m as  h N 

O’  O tn  fV  9*5 

K -fl  H -flo<  ® 

o # <fi  e vt  h 

«v»  «f  «♦>«<©  ^ 

^ «pcj  *=S  es*J  5=®  5^ 


ffe  «#  © e=4  <£ 

»-<  r*  <#  O «*» 

ff4H#  ^flV  ® 
<f>  r*  «T  «V  <0 

^ **©  ® «n  «*  © 

<#■  sx  avi  ® 0 

O « O C ® ® 

<«  w ^ tf 


X «=J 
UJ  ® 
© **. 
X « 
ua  ® 
G=  <as 
uy 


©06000 
o o o © @ © 
© o o o © o 
eoo  oo  o 

® eX  © CVS  © 

i*a  «\*  o ® 0 
**  'G  & m e <& 


© ® 


© © 


^1  «*5  ««  0> 


I 

fe 

cu 

p 

3 

be 


(•= 


C-4 

3! 


B 

B 

8 

8 

8 

8 

8 

8 

8 

8 


© © © © © © 
© © o o e o 
© © © © © © 
© © © o © o 

© •*  © g*fc  V*  © 
© f*>  o*  0 fl-<  © 

iw  «r  0 «\  0 0 


8 ft 

C A 

8 

8 

8 

8 

8 

I 

( 

I 

e 

9 


8 3i  cvi  w>  os*  et  0 

8 © 

8 ft 

8 


9-34 


Example  of  NLS  output  (continued) 
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Example  of  NLS  output  (continued) 


APPROXIMATION  BASED  ON  ASSUMPTION  THAT  RESIDUALS  ARE  SHALL 
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Example  of  NLS  output  (continued) 


Nonlinear  Least  Squares  Estimation 
With  User-Supplied  Analytic  Derivatives 


MAIN  PROGRAM 


MODEL  SUBROUTINE* 


PROGRAM  E X AM  PL 

C 

C DEMONSTRATE  NLSD  USING  SINGLE  PRECISION  VERSION  OF  STARPAC 

C RUN  ON  CYRER  180/840. 

C 

C OUTPUT  UNIT  IS  6 (AUTOMATICALLY  EOUATED  TO  FILE  TAPE6  ON  CY8ERS) 

C ISEE  CHAPTER  1*  SECTION  D.4J 

C 

C N.B.  DECLARATION  OF  Y»  XM,  PAR  AND  RES  MUST  BE  CHANGED  TO  DOUBLE  PRECISION 

C IF  DOUBLE  PRECISION  VERSION  OF  STARPAC  IS  USEO. 

C 

REAL  Y ( 10 ) , XM ( 10*  5 ) » PAR(5I,  RES(IO) 

DOUBLE  PRECISION  0STAM200) 

C 

EXTERNAL  NLSMDL*  NL SDR  V 

C 

COMMON  /CSTAK/  DSTAK 

c 

C SPECIFY  NECESSARY  DIMENSIONS 

C 

LDSTAK  - 200 
IXM  * 10 

C 

C READ  NUMBER  OF  PARAMETERS 

C STARTING  VALUES  FOR  PARAMETERS 

C NUMBER  OF  OBSERVATIONS  AND  NUMBER  OF  INDEPENDENT  VARIABLES 

C INDEPENDENT  AND  DEPENDENT  VARIABLES 

C 

READ  100*  NPAR 

RE  AO  101*  ( PAR  ( I ) » I" 1*  NPAR ) 

READ  100*  N,  M 

READ  101*  UXN«I»J)»  I-1,N),  J •! » M 1 * C Y( I J » I-1,N) 

C 

C PRINT  TITLE  ANO  CALL  NLSD  TO  PERFORM  NONLINEAR  REGRESSION 

C WITH  USER-SUPPLIED  DERIVATIVES 

C 

UR ITE  (6*  102 } 

CALL  NLSD  (Y,  XN,  N*  M»  IXM*  NLSMDL*  NLSORV*  PAR*  NPAR*  RES* 

* LOSTAtO 

C 

STOP 

C 

C FORMAT  STATEMENTS 

C 

100  FORMAT  (215  } 

101  FORMAT  (6F6.3) 

102  FORMAT  C1RESULTS  OF  STARPAC* 

« * NONLINEAR  LEAST  SQUARES  SUBROUTINE  NLSD*) 

END 

SUBROUTINE  NLSMDL  (PAR*  NPAR*  XN*  N*  M*  IXM*  PV> 

C 

C SUBROUTINE  TO  COMPUTE  PREDICTED  VALUES  OF  DEPENDENT  VARIABLE 

C 

C N.B.  DECLARATION  OF  PAR*  XM  AND  PV  MUST  BE  CHANGED  TO  DOUBLE  PRECISION 

C IF  DOUBLE  PRECISION  VERSION  OF  STARPAC  IS  USEO. 

C 

REAL  PAR(NPAR)*  XM(IXN*M),  PV(N) 

C 

DO  10  I - 1*  N 

PV(I)  • P AR  ( 1 ) * XM ( I * 1)  ♦*  P AR ( 2 ) 

10  CONTINUE 

C 

RETURN 

END 


Figure  F-2a 

Example  program  using  NLSD 


DERIVATIVE  SUBROUT INE  6 


SUBROUTINE  NLSBBV  IPAR*  NBAS*  XNC  N»  N»  IXHt  08 

C 

C SUBROUTINE  TQ  CONFUTE  THE  PARTIAL  DERIVATIVE  ( JACOBI  AN  i NATRIX 

C 

C Mel.  DECLARATION  OF  BAR*  IN  AND  0 MUST  BE  CHANCED  TO  DOUBLE  PRECISION 

C IF  DOUBLE  BRECISION  VERSION  OF  SYARBAC  IS  USED. 

C 

REAL  BAR(NPAR)#  XNiIXN#H|»  DtN»NPAR> 

C 

DO  10  I > I*  N 

DU»1S  « XM*I»1»  *»  BARI2I 

DU«I>  * BARU»  * XNU»1)  •*  BAR  (21  ♦ ALOCCXNI  1*11  » 

10  CONTINUE 
C 

RETURN 

END 


DATA!  £ 

0.723  A. 000 
0 1 

1.309  1.471  1.490  1.369  1.611  1.660 
2.136  3.421  3.397  4.340  4.682  3.660 


Figure  F-2b 

Example  program  using  NLSD  (continued) 


Example  of  NLSD  output 
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Example  of  NLSD  output  (continued) 
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Example  of  NLSD  output  (continued) 
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Example  of  NLSD  output  (continued) 
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Example  of  NLSD  output  (continued) 


Derivative  Step  Size  Selection 


NAIM  PROGRAM  I 


PROGRAM  EXANPL 

C 

C DEMONSTRATE  STPLS  USING  SINGLE  PRECISION  VERSION  OF  STARPAC 
C RUN  ON  CYBER  100/040. 

C 

C OUTPUT  UNIT  IS  6 (AUTOMATICALLY  EQUATED  TO  FILE  TAPE6  ON  CYBERSt 
C (SEE  CHAPTER  1#  SECTION  0.4) 

C 

C N.B.  DECLARATION  OF  XM*  PAR  AND  STP  MUST  BE  CHANGED  TO  DOUBLE  PRECISION 
C IF  DOUBLE  PRECISION  VERSION  OF  STARPAC  IS  USED. 

C 

REAL  IN(10*5>*  PARIS) * STPISS 
DOUBLE  PRECISION  DSTAM200) 

C 

EXTERNAL  NLSNOL*  DERI V 

C 

COMMON  /CSTAK/  OSTAK 
C 

C SPECIFY  NECESSARV  DIMENSIONS 

C 

LOST AK  • 200 
IXN  • 10 

C 

C READ  NUMBER  OF  PARAMETERS 

C STARTING  VALUES  FOR  PARAMETERS 

C NUMBER  OF  OBSERVATIONS  AND  NUMBER  OF  INDEPENDENT  VARIABLES 

C INDEPENDENT  VARIABLES 

C 

READ  160*  NPAR 

READ  101*  (PAR (II#  I*1*NPARI 

READ  100*  N*  M 

READ  101*  I (XN(I»J)»  I»1*N)#  J«1*NI 
C 

C PRINT  TITLE  AND  CALL  STPLS  TO  SELECT  STEP  SUES  FOR 
C APPROXIMATING  DERIVATIVES 
C 

WRITE  (0*  102) 

CALL  STPLS  (XM*  N*  H*  IXN*  NLSNOL*  PAR*  NPAR*  IDSTAK*  STP) 

C 

STOP 

C 

C FORMAT  STATEMENTS 

C 

100  FQRNAY  (215) 

1@1  FORMAT  (6F6.3) 

102  FORMAT  CIRESULTS  OF  STARPAC”* 

« « DERIVATIVE  STEP  SUE  SELECTION  SUBROUTINE  STPLS”) 

ENO 


MODEL  SUBROUTINE! 

C 

C 

C 

C 

C 

C 

C 


c 


SUBROUTINE  NLSNOL  (PAR*  NPAR*  XM*  M*  N*  IXN*  PV) 

SUBROUTINE  TO  CONPUTE  PREDICTED  VALUES  OF  DEPENDENT  VARIABLE 

N.B.  DECLARATION  OF  PAR*  XN  AND  PV  NUST  BE  CHANGED  TO  DOUBLE  PRECISION 
IF  DOUBLE  PRECISION  VERSION  OF  STARPAC  IS  USED. 

RIAL  PAR (NPAR ) * XH(IXN*N)»  PV(N) 

DO  10  I • l*  N 

PV(1)  * PAR(l)  4 XM ( I * 1)  *4  PAR ( 2 ) 

16  CONTINUE 

RETURN 

END 


DATA*  2 

6.72S  4.006 
6 1 

le36«  1.471  1.406  1.S6S  1.011  1.606 


Figure  F~3a 


Example  program  using  STPLS 
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Example  of  STPLS  output 


Derivative  Checking 


MAIN  PROCRANl 

C 

C 

C 

c 

c 

c 

c 

c 

c 

c 


c 

€ 

C 

c 

e 


c 

e 

c 

t 

c 

e 


e 

€ 


PROCRAM  EXAMPL 

DEMONSTRATE  DCKLS  USINC  SINCE!  PRECISION  VERSION  OF  STARPAC 
RUN  ON  CYBER  1B0/640. 

OUTPUT  UNIT  IS  6 (AUTOMATICALLY  EQUATED  TO  FILE  TAPE6  ON  CYBERS) 
CSEE  CHAPTER  1*  SECTION  0.4] 

N*B.  DECLARATION  OF  XN  AND  PAR  MUST  BE  CHANCED  TO  DOUBLE  PRECISION 
IF  OOUBLE  PRECISION  VERSION  OF  STARPAC  IS  USED. 

REAL  XH( 10*5 ) * PARIS) 

DOUBLE  PRECISION  DSTAK<200» 

EXTERNAL  NLSNDL*  NLSDRV 

COMMON  /CSTAK / OSTAK 

SPECIFY  NECESSARY  DIMENSIONS 

LOSTAK  • 200 
IXR  • 10 

READ  HUMBER  OF  PARAMETERS 

STARTINC  VALUES  FOR  PARAMETERS 

NUMBER  OF  OBSERVATIONS  AND  NUMBER  OF  INDEPENDENT  VARIABLES 
INDEPENDENT  VARIABLES 

READ  IDO*  NPAR 

READ  101*  i PAR  ID*  1*1»NPAR) 

READ  100*  N*  M 

READ  101*  <(IK(I*J)»  I ®1*N) » <g-l*Hl 

PRINT  TITLE  ANO  CALL  DCKLS  TO  PERFORM  DERIVATIVE  CHECKINC 


WRITE  (4*  102) 

CALL  DCKLS  (XH»  N»  N»  IXN*  NLSNDL*  NLSDRV*  PAR*  NPAR*  LOSTAK) 
C 

STOP 

C 

C FORMAT  STATEMENTS 

C 

100  FORMAT  (219) 

101  FORMAT  (4P4.3) 

102  FORMAT  C'lRISULTS  OF  STARPAC • » 

4 « DERIVATIVE  CHECKINC  SUBROUTINE  DCKLS 8 ) 

END 


MODEL  SUCROUTINEl  SUBROUTINE  NLSMDL  (PAR*  NPAR*  IN*  N*  N*  IXN*  PVI 

C 

C SUBROUTINE  TO  COMPUTE  PREDICTED  VALUES  OF  DEPENDENT  VARIABLE 
C 

C N.B.  DECLARATION  OF  PAR*  XM  AND  PV  MUST  BE  CHANCED  TO  OOUBLE  PRECISION 
C IF  DOUBLE  PRECISION  VERSION  OF  STARPAC  IS  USED. 

C 

REAL  PAR(NPAR)*  XN(IXN*N)*  PV(N) 

C 

DO  10  I - 1*  N 

PVC1)  • PAR(l)  * XMCI,  1)  •*  PAR(2) 

10  CONTINUE 

e 

RETURN 

END 


Figure  F-4a 

Example  program  using  DCKLS 
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DERIVATIVE  SUBROUTINE* 

e 

c 

c 

c 

c 

c 

c 

c 

c 

c 


e 


SUBROUTINE  NLSDRV  (EAR*  NP  AR » XM»  N/>  N t IXh,  01 

SUBROUTINE  TO  COMPUTE  THE  PARTIAL  DERIVATIVE  (JACOBIAN)  MATRIX 

DERIVATIVE  WITH  RESPECT  TO  EIRST  PARAMETER  HAS  BEEN  CODED 
INCORRECTLY  TO  DEMONSTRATE  ERROR  DETECTION  CAPABILITIES 

N.B.  DECLARATION  OF  PAR*  XN  AND  0 MUST  BE  CHAN6ED  TO  DOUBLE  PRECISION 
IF  DOUBLE  PRECISION  VERSION  OF  STARPAC  IS  USED. 

REAL  PAR(NPAR)*  XM(IXN»N)«  D(N*NPAR I 

DO  10  I • 1*  N 

0(1*1)  ■ IN( 1*1 ) A PAR (2 ) 

0(1*2)  • PAR(l)  * XH( 1*1 ) **  PAR (1 ) e AL06( XN( 1* 1 ) ) 

10  CONTINUE 

RETURN 

END 


OATAl  2 

0.000  0.000 

6 I 

1.909  1.471  1.490  1.969  1.611  1.680 


Figure  F-4b 

Example  program  using  DCKLS  (continued) 


% 

w 

© 


i*4 

© 


» 


©> 

© 

©■ 

© 

© 

X 

z 

M= 

<m 

© 

*r> 

M3 

M 

© 

z 

Z 

z 

w 

M* 

«> 

© 

mi 

MB  £= 

►*=  <=£ 

X X 

©i  © 

M3  Q*4 

(49  © 

Ml 

X 

© X 

O 

© w 

* o 

© 

z 

X *« 

© « 

© 

© 

ve 

6=0  ms 

U M 

© 

a»5 

AS  %* 

z m 

e 

M 

Ml 

* 

^3  Oft 

M (40 

«« 

u* 

© © 

MS 

(41 

o 

© 

© 

« 

© 

© 

X 

MD 

z 

© 

o 

Z 

z 

© 

es* 

© 

W 

6*1 

M* 

z 

(M 

K 

w 

MS 

X 

Ml 

M3 

o 

X 

*«  c 

6*1 

O X 

© 

© 

N>  X 

© 

MS  M 

© 

<*• 

oW) 

© a 

<• 

© 

© 

M0  449 

«*9  ck9 

«0 

x © 

© 

U M 

© © 

O 

»* 

ol 

Ml  © 

© © 

© © 

64 

© © 

© 

© 

X 

u u 

U=  44, 

MS  Ul 

¥* 

Z 

U 6* 

z 

*t  «*> 

149  HI 

Ml 

© X 

Ml 

M 

Mi 

e=o 

M> 

© o 

X 

© 

© 

Ml  ^ 

M 

►» 

© © 

u 

© © 

<U 

MU  Z 

Ml 

6*1  © 

Ml 

o 

►»  © 

US 

X 

X «M 

X 

© 

© 

u 

© 

U 

z s= 

© 

© 

M<  © 

z 

6*1 

6*1  X 

w 

Ul 

X 

X 

X 

X 

MS 

14 

o © 

Z 

MO 

M M 

M* 

9 

III 

© u 

M 

►>  X 

M> 

© 

© Ml 

© 

© 6*1 

© 

© © 

© X 

1« 

X 

X o 

o 

X 

649  X 

o 

V» 

© o 

►« 

M 

M.  Z 

o 

8rC  #> 

# « 

M=  ** 

o 

Ul 

MS 

MO 

© 

© 6*1 

© 

© ♦ 

• 

6*fl  <4®  © 

o 

•ft 

© © 

© 

6*1 

6*1  © 

© 

•* 

6*1  «• 

» 

Z X © 

o 

149 

z 

M3 

o 

O 6*1 

o 

z 

O « 

Z « 

© W © 

o 

X 

© 

© 

o 

m 

o 

« 

M)  * 

* ^ W 

o 

• 

z 

X X 

*4 

• 

^ «■ 

a?  • 

© m 

o 

z 

© © 

M5 

M 

u *- 

9* 

M 

© * 

w * 

© © 

• 

Ul 

ms  © 

•1 

m: 

© 

ft.  •#- 

m «• 

• © 

© 

M US 

0 

X 6*1 

X 

m *> 

X «> 

m 

© 

© 

•0  Ml 

© 

*- 

x z 

© 

© «• 

M «> 

4 

© 

M3 

CM 

*- 

X 

6*1 

1*1 

«• 

© Mi 

f«9 

© 

►» 

6*1 

© 

V* 

**>  «* 

0*9  # 

z 

© © 

Ml 

M 

© 14 

O -I 

© 

•» 

X # 

MS 

**>  © 

© 

© 

OX© 

o 

m>  * 

MJ  #> 

1 

© 

** 

X 

o <•> 

<• 

© X 

M 

64 

6*1  «A 

64 

♦ 

© » 

© 

149  M 

o 

O 

© 6*1 

O 

kf»  •*■ 

X « 

C4» 

tft  © 

z © 

M=  <*■ 

» #■ 

© 

© © 

© 

© 

© -1 

© 

€> 

© c 

m 

K 

Ul 

6*1 

z © 

6*1 

3 t 

149  *> 

ms 

© 

© 

© 

X 

© 

«■ 

© * 

© 

*4  «¥) 

Z 

*4 

z 

z 

X 1 

z 

Ml  * 

♦ 

Z 

w 

© 

© 

o 

© 

« €> 

© * 

MO 

z 

z 

© 

z 

9-48 


Example  of  DCKLS  output 


G.  Acknowledgments 


The  subroutines  used  to  compute  the  nonlinear  least  squares  solution  are 
those  referenced  in  Dennis  et  al.  [1981] . The  algorithms  used  to  select 
optimum  step  sizes  for  numerical  derivatives,  and  to  check  analytic 
derivatives  were  developed  by  Schnabel  [1982] . The  printed  output  for  the 
nonlinear  least  squares  subroutines  has  been  modeled  on  the  linear  least 
squares  output  used  by  OMNITAB  II  [Hogben  et  al.  1971], 
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CHAPTER  10 


DIGITAL  FILTERING 


A.  Introduction 

STARPAC  contains  16  subroutines  for  digital  filtering  time  series.  These 
include  subroutines  which:  compute  a least  squares  approximation  to  an  ideal 
low-pass  filter;  perform  symmetric  linear  filter  operations;  sample  values 
from  a series;  perform  autoregressive  (or  difference)  filter  operations;  and 
compute  the  gain  function  of  any  symmetric  linear  filter  and  the  gain  and 
phase  functions  of  any  autoregressive  (or  difference)  filter. 

Users  are  directed  to  §B  for  a brief  description  of  the.  subroutines.  The 
declaration  and  CALL  statements  are  given  in  §C  and  the  subroutine  arguments 
are  defined  in  §D.  The  algorithms  used  and  the  output  produced  by  these 
subroutines  are  discussed  in  §E.  Sample  programs  and  their  output  are  shown 
in  §F. 


B . Subroutine  Descriptions 
Ed  Symmetric  Linear  Filter  Subroutines 

Subroutine  LPCOEF  computes  symmetric  linear  low-pass  filter  coefficients 
using  a least  squares  approximation  to  an  ideal  low-pass  filter  that  has 
convergence  factors  which  reduce  overshoot  and  ripple  [Bloomfield,  1976], 
This  low-pass  filter  has  a transfer  function  which  changes  from  approximately 
one  to  zero  in  a transition  band  about  the  ideal  cutoff  frequency  FC,  that  is 
from  (FC  - 1/K)  to  (FC  + 1/K),  as  shown  in  figure  B.l-1.  The  user  must 
specify  the  cutoff  frequency  in  cycles  per  sample  interval  and  the  number  of 
filter  coefficients,  which  must  be  odd.  The  user  must  also  choose  the  number 
of  filter  terms,  K,  so  that  (FC  - 1/K)  > 0 and  (FC  + 1/K)  < 0.5.  In  addition, 
K must  be  chosen  as  a compromise  between: 

1)  A sharp  cutoff,  that  is,  1/K  small;  and 

2)  Minimizing  the  number  of  data  points  lost  by  the  filtering  operations 
( (K  - 1 ) / 2 data  points  will  be  lost  from  each  end  of  the  series) . 

The  subroutine  returns  the  normalized  low-pass  filter  coefficients.  There  is 
no  printed  output. 

For  any  low-pass  filter  there  is  a corresponding  high-pass  filter 
equivalent  to  subtracting  the  low-pass  filtered  series  from  the  original 
series.  Subroutine  HPCOEF  returns  symmetric  linear  high-pass  filter 
coefficients  computed  from  user  supplied  low-pass  symmetric  linear  filter 
coefficients.  The  number  of  filter  coefficients  must  be  odd.  There  is  no 
printed  output. 
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LEAST  SQUARES  APPROX  SHAT  ION  TO  IDEAL  LOW  PASS  FILTER  WITH  TRANSITION  BAND 


10-2 


Transfer  function  of  41-term  least  squares  low-pass  filter 
with  a cutoff  frequency  of  1/22  cycles  per  sample  interval 


Subroutine  MAFLT  performs  a simple  moving  average  filter  operation  on  the 
input  series  using  the  simple  moving  average  filter  defined  by 

HMA(J)  = 1/K  for  J = 1,  K. 

The  user  must  specify  the  number  of  filter  coefficients,  K,  which  must  be  odd; 
the  subroutine  returns  the  filtered  series  and  the  number  of  observations  in 
the  filtered  series.  There  is  no  printed  output. 

Subroutine  SLFLT  performs  a symmetric  linear  filter  operation  with  user 
supplied  coefficients  and  returns  the  filtered  series  to  the  user.  The  filter 
coefficients  must  be  normalized  on  input  to  SLFLT.  The  filtered  series  and 
the  number  of  observations  in  the  filtered  series  are  returned.  There  is  no 
printed  output. 

t"  v» 

Subroutine  SAMPLE  samples  every  NScn  observation  from  an  input  series. 
If  the  input  series  was  obtained  using  an  NS  term  low-pass  filter,  this 
sampling  rate  removes  the  autocorrelation  introduced  by  the  filtering 
operation.  This  subroutine  returns  the  series  of  sampled  observations  and  the 
number  of  observations  in  the  series.  There  is  no  printed  output. 

Subroutine  LOPASS  computes  low-pass  filter  coefficients  as  described  for 
subroutine  LPCOEF  and  then  performs  the  filtering  operation  described  for 
subroutine  SLFLT.  The  user  must  specify  the  cutoff  frequency  in  cycles  per 
sample  interval  and  the  number  of  filter  terms,  which  must  be  odd.  The 
subroutine  returns  the  normalized  filter  coefficients,  the  filtered  series  and 
the  number  of  observations  in  the  filtered  series.  There  is  no  printed 
output. 

Subroutine  HIPASS  computes  the  high-pass  filter  coefficients  equivalent 
to  using  HPCOEF  with  the  input  low-pass  filter  coefficients  supplied  by  LPCOEF 
and  performs  the  filtering  operation  described  for  subroutine  SLFLT.  The  user 
must  specify  the  cutoff  frequency  in  cycles  per  sample  interval  and  the  number 
of  filter  terms,  which  must  be  odd.  The  subroutine  returns  the  filter 
coefficients,  the  filtered  series  and  the  number  of  observations  in  the 
filtered  series.  There  is  no  printed  output. 


B o 2 Autoregressive  or  Difference  Linear  Filter  Subroutines 

Subroutine  ARFLT  subtracts  the  series  mean  from  each  observation  and 
performs  an  autoregressive  linear  filter  operation  with  user  supplied  filter 
coefficients.  This  subroutine  returns  the  filtered  series  and  the  number  of 
observations  in  the  filtered  series.  There  is  no  printed  output. 

Subroutine  DIF  performs  a first  difference  filter  operation  on  the  input 
series.  It  returns  the  differenced  series  and  the  number  of  observations  in 
the  differenced  series.  There  is  no  printed  output. 

Subroutine  DIFC  performs  a user  controlled  differencing  operation.  It 
returns  the  order  of  the  difference  filter  specified,  the  coefficients  of  the 
difference  filter,  the  differenced  series  and  the  number  of  observations  in 
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the  differenced  series.  This  subroutine  can  be  used  as  a high-pass  filter  or 
for  differencing  series  in  the  style  of  Box  and  Jenkins  [1976]  . There  is  no 
printed  output. 

Subroutines  DIFM  and  DIFMC  are  the  same  as  DIF  and  DIFC,  respectively, 
except  that  the  input  series  may  contain  missing  data.  A missing  value  code 
must  be  used  within  the  input  series  to  specify  time  points  without  an 
observed  value.  The  difference  between  a missing  value  and  an  observed  value, 
or  between  two  missing  values,  will  result  in  a missing  value  in  the 
differenced  series;  the  missing  value  code  used  in  the  differenced  series  is 
also  returned  to  the  user.  Users  should  note  that  the  number  of  missing 
values  may  be  significantly  increased  by  the  differencing  operation. 


B.3  Gain  and  Phase  Function  Subroutines 


Subroutine  GFSLF  computes  the  gain  function  of  a symmetric  linear  filter. 
The  printed  output  consists  of  a plot  of  the  gain  function  versus  frequency. 

Subroutine  GFSLFS  is  the  same  as  GFSLF  but  allows  the  user  to  specify 
various  options  which  are  preset  in  GFSLF,  including  the  frequency  range,  the 
number  of  frequencies  for  which  the  gain  function  is  to  be  computed  and  the 
type  of  plot  to  be  used.  In  addition,  the  gain  function  is  returned  to  the 
user,  permitting  the  use  of  other  methods  of  displaying  the  results. 

Subroutine  GFARF  computes  the  gain  and  phase  functions  of  either 
autoregressive  or  difference  filters.  The  output  consists  of  a plot  of  the 
gain  and  phase  functions  versus  frequency. 

Subroutine  GFARFS  is  the  same  as  GFARF  but  provides  the  user  with  the 
same  options  as  are  available  for  subroutine  GFSLFS. 


C o Subroutine  Declaration  and  CALL  Statements 

NOTES  Argument  definitions  and  sample  programs  are  given  in  §D  and  §F, 
respectively.  The  conventions  used  to  present  the  following  declaration  and 
CALL  statments  are  given  in  chapter  1,  §B  and  §D. 


Subroutines  Supporting  Symmetric  Linear  Filter  Operations 

LP'COEF:  Compute  symmetric  linear  low-pass  filter  coefficients;  return  filter 

coefficients  (no  printed  output) 

<real>  HLP(k) 

CALL  LPCOEF  (FC,  K,  HLP) 
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HPCOEF:  Compute  symmetric  linear  high-pass  filter  coefficients;  return 

coefficients  (no  printed  output) 

<real>  HLP(fc),  HHP  (fc  ) 

t 

CALL  HPCOEF  (HLP,  K,  HHP) 

MAFLT:  Perform  simple  moving  average ; return  filtered  series  (no  printed 

output) 

<real>  Y(n),  YF  (n ) 

CALL  MAFLT  (Y,  N,  K,  YF , NYF ) 

SLFLT : Perform  symmetric  linear  filter  operation  with  user- supplied  filter 

coefficients;  return  filtered  series  (no  printed  output) 

<real>  Y(n),  H (fc),  YF (n) 

$ 

CALL  SLFLT  (Y,  N,  K,  H,  YF , NYF) 

SAMPLE:  Sample  (extract)  every  NS ^ observation  from  a series;  return 

sampled  series  (no  printed  output) 

<real>  Y(n),  YS(n) 

I 

CALL  SAMPLE  (Y,  N,  NS,  YS , NYS ) 

LOPASS:  Filter  series  with  symmetric  linear  low-pass  filter;  return  filtered 

series  (no  printed  output) 

<real>  Y(n),  HLP(k),  YF(n) 


CALL  LOPASS  (Y,  N,  FC , K,  HLP,  YF , NYF) 


HIPASS:  Filter  series  with  symmetric  linear  high-pass  filter;  return 

filtered  series  (no  printed  output) 

<real>  Y(n),  HHP(fc),  YF (n) 

S 

CALL  HIPASS  (Y,  N,  FC,  K,  HHP,  YF , NYF ) 


Subroutines  for  Autoregressive  or  Difference  Linear  Filters 

ARFLT : Perform  autoregressive  filter  operation  with  user-supplied  filter 

coefficients;  return  filtered  series  (no  printed  output) 

<real>  Y(n),  PHI (iar»),  YF(n) 
i 

CALL  ARFLT  (Y,  N,  IAR,  PHI,  YF , NYF) 

DIF o Perform  first- difference  filter  operation;  return  differenced  series 
(no  printed  output) 

<real>  Y(n),  YF(n) 

Z 

CALL  DIF  (Y,  N,  YF , NYF) 

DIFC:  Perform  user- specif ied  difference  filter  operation;  return 

differenced  series  (no  printed  output) 

INTEGER  ND(n/ac),  IOD(n/ac) 

<real>  Y(n),  YF(n),  PHI (iar*) 

DOUBLE  PRECISION  DSTAK (Idstak) 

COMMON  /CSTAK/  DSTAK 

CALL  DIFC  (Y,  N,  NFAC,  ND,  IOD,  IAR,  PHI,  LPHI,  YF , NYF,  LDSTAK) 

DIFM:  Perform  first-difference  filter  operation  on  series  with  missing 

data;  return  differenced  series  (no  printed  output) 

<real>  Y(n),  YF(n) 


CALL  DIFM  (Y,  YMISS,  N,  YF , YFMISS,  NYF) 
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DIFMC: 


GFSLF : 


GFSLFS: 


GFARF: 


Perform  user- specified  difference  filter  operation  on  series  with 
missing  data;  return  differenced  series  (no  printed  output) 

INTEGER  ND (nfac),  lOD(nfac) 

<real>  Y(n),  YF(n),  PHI (iar) 

DOUBLE  PRECISION  DSTAK (Idstak) 

COMMON  / CSTAK/  DSTAK 


CALL  DIFMC  (Y,  YMISS,  N,  NFAC,  ND,  IOD,  IAR,  PHI,  LPHI,  YF , 
1 YFMISS,  NYF , LDSTAK) 


Subroutines  for  Computing  the  Gain  and  Phase  Functions 
Compute  and  plot  gain  function  of  symmetric  linear  filter 

<real>  H (k.) 

$ 

CALL  GFSLF  (H,  K) 


Compute  and  optionally  plot  gain  function  of  symmetric  linear  filter 
with  user-supplied  control  values;  return  gain  function  values  and 
corresponding  frequency  values 

<real>  H(k),  GAIN(n/),  FREQ(nf) 

DOUBLE  PRECISION  DSTAK (Idstak) 

COMMON  /CSTAK/  DSTAK 


CALL  GFSLFS  (H,  K,  NF , FMIN,  FMAX , GAIN,  FREQ,  NPRT,  LDSTAK) 


Compute  and  plot  gain  and  phase  functions  of  autoregressive  or 
difference  filter 

<real>  PHI  (iar®) 


CALL  GFARF  (PHI,  IAR) 
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GFARFS:  Compute  and  optionally  plot  gain  and  phase  functions  of 

autoregressive  or  difference  filter;  with  user- supplied  control 
values;  return  gain  and  phase  function  values  and  corresponding 
frequency  values 

<real>  PHI( iar),  GA.IN(nf)  , PHAS(nf),  FREQ(nf) 

DOUBLE  PRECISION  DSTAK(ldstak) 

COMMON  / CSTAK/  DSTAK 


CALL  GFARFS  (PHI,  IAR,  NF , FMIN,  FMAX , GAIN,  PHAS,  FREQ,  NPRT, 
1 LDSTAK) 


D.  Dictionary  of  Subroutine  Arguments  and  COMMON  Variables 


NOTE:  — > indicates  that  the  argument  is  input  to  the  subroutine  and  that 

the  input  value  is  preserved; 

<—  indicates  that  the  argument  is  returned  by  the  subroutine; 

<->  indicates  that  the  argument  is  input  to  the  subroutine  and  that 
the  input  value  is  overwritten  by  the  subroutine; 

— - indicates  that  the  argument  is  input  to  some  subroutines  and  is 
returned  by  others; 

***  indicates  that  the  argument  is  a subroutine  name; 

° * * indicates  that  the  variable  is  passed  via  COMMON* 


DSTAK  The  DOUBLE  PRECISION  vector  in  COMMON  /CSTAK/  of  dimension  at 

least  LDSTAK.  DSTAK  provides  workspace  for  the  computations.  The 
first  LDSTAK  locations  of  DSTAK  are  overwritten  during  subroutine 
execution. 

FC  “>  The  cutoff  frequency  for  the  filter,  in  cycles  per  sample 

interval.  FC  must  lie  between  0.0  and  0.5. 

FMAX  -“>  The  maximum  frequency,  in  cycles  per  sample  interval,  at  which  the 
gain  and  phase  functions  are  computed  (0.0  < FMIN  < FMAX  < 0.5). 
The  default  value  is  0.5.  If  FMAX  is  outside  the  range  FMIN  to 
0.5  or  is  not  an  argument  in  the  CALL  statement  the  default  value 
is  used. 

FMIN  — > The  minimum  frequency,  in  cycles  per  sample  interval,  at  which  the 
gain  and  phase  functions  are  computed  (0.0  < FMIN  < FMAX  < 0.5). 
The  default  value  is  0.5.  If  FMIN  is  outside  the  range  0.0  to 
FMAX  or  is  not  an  argument  in  the  CALL  statement  the  default  value 
is  used. 

FREQ  <---■  The  vector  of  dimension  at  least  NF  containing  the  NF  frequencies 
at  which  the  gain  and  phase  functions  are  computed. 

GAIN  <—  The  vector  of  dimension  at  least  NF  containing  the  NF  gain 
function  values  over  the  range  FMIN  to  FMAX. 

— continued  — 
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For  symmetric  linear  filters: 


The  gain  function  of  a symmetric  linear  filter  is 
K 

GAIN(I)  = | l (H(J)  cos  [ 2ir  | K^- J | (FMIN+Ax)]}| 

J=1 

for  I = 1,  NF,  where 

is  the  midpoint  of  the  symmetric  filter,  Km  = (K+l)/2,  and 

Aj  is  the  frequency  increment,  defined  as 

Aj  = 2 ( I— 1 ) (FMAX-FMIN)  / (NF-1) 

There  is  no  phase  change  in  a symmetric  linear  filter. 

For  autoregressive  (or  difference)  filters: 

The  gain  and  phase  functions  of  an  autoregressive  (o 
difference)  filter  are 

GAIN(I)  » 

IAR 

|l  - l {PHI(J)  (cos[2ttJ(FMIN+AI)]  + i sin[  2tt  J(FMIN+A  I)] ) } 
J=1 

and 

IAR 

l { PHI ( J ) sin[iTT  J(FMIN+AI)]} 

J=1 

PHAS(I)  = Arctan  — — — 

IAR 

1 - l { PHI  ( J ) cos [ iir  J(FMIN+AI)]} 

J=1 

for  I = 1,  2,  ...,  NF,  where 

1/2 

i is  the  complex  value  (-1)  ; and 

Aj  is  the  frequency  increment,  defined  as 
AX  = 2(1-1) (FMAX-FMIN)  / (NF-1). 

->  The  vector  of  dimension  at  least  K containing  filter  coefficients 
which  must  be  symmetric  about  H((K+l)/2). 
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HHP 


< — The  vector  of  dimension  at  least  K containing  the  K high-pass 
filter  coefficients,  which  are  symmetric  about  HHP[ (K+l ) /2) . The 
high-pass  filter  coefficients  are  computed  from  the  low-pass 
coefficients  by 


K 

HHP(J)  = 1- [ HLP( J ) / l HLP(J)]  for  J = V 

L=1 


K 

HHP(J)  = -[ HLP( J ) / l HLP ( J ) ] for  J = 1,  . ..,  K^-l , K^+l , . ..,  K. 

L=1 

HLP  - — - The  vector  of  dimension  at  least  K containing  the  K low-pass 

filter  coefficients,  which  must  be  symmetric  about  HLP[ (K+l ) / 2 ] . 
HLP  must  be  input  to  HPCOEF;  it  is  returned  by  LPCOEF  and  LOPASS. 

For  LPCOEF  and  LOPASS,  HLP  is  defined  by 

K 

HLP(J)  = hj  / l hj  for  J = 1 K, 

1=1 


where 

hj  is  computed  by 

hj  = 2*  FC  for  J = ^ 

sin[2ir  Ik^-J  | FC]  sin[2Tr  | K^-J  | / K] 
hJ  = ________  « __________  for  J 

» |Km-J|  2*  |Km-j|  / K 

with  the  midpoint  of  the  filter,  Km  = (K+l)/2. 

This  low-pass  filter  has  a transfer  function  which  changes  from 
approximately  one  to  zero  in  a transition  band  about  the  ideal 
cutoff  frequency  FC,  that  is  from  (FC  - 1/K)  to  (FC  + 1/K),  as 
shown  in  figure  B.l-1. 

IAR  — The  number  of  coefficients  in  the  autoregressive  (or  difference) 
filter,  including  zero  coefficients.  Equivalently,  IAR  is  the 
maximum  order  of  the  backward  shift  operator.  IAR  must  be  input 
to  ARFLT,  GFARF  and  GFARFS;  it  is  returned  by  DIFC  and  DIFMC.  IAR 
is  defined  by 

NDF 

IAR  = l [ IOD(J)»ND(J)] . 

J=1 


— 1 , . . • , 
Km-1,  VI, 
...  , K 
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IERR 


IOD 

K 


LDSTAK  - 


LPHI 
N 

ND 
NF 


**  An  error  flag  returned  in  COMMON  /ERRCHK/.  [See  chapter  1,  § D . 5 . ] 
Note  that  using  (or  not  using)  the  error  flag  will  not  affect  the 
printed  error  messages  that  are  automatically  provided  even  when 
the  user  has  suppressed  the  normal  printed  output. 

IERR  = 0 indicates  that  no  errors  were  detected. 

IERR  = 1 indicates  that  improper  input  was  detected. 

— > The  vector  of  dimension  at  least  NFAC  containing  the  NFAC  values 
designating  the  order  of  each  difference  factor. 

— > The  number  of  coefficients  in  the  symmetric  linear  filter.  K must 

be  odd.  For  LPCOEF,  LOPASS,  and  HIPASS,  the  user  must  choose  the 

number  of  filter  terms,  K,  so  that  (FC  - 1/K)  > 0 and 

(FC  + 1/K)  < 0.5.  In  addition,  K must  be  chosen  as  a compromise 
between: 

1)  A sharp  cutoff,  that  is,  1/K  small;  and 

2)  Minimizing  the  number  of  data  points  lost  by  the  filtering 
operations  (K  - 1 ) / 2 data  points  will  be  lost  from  each  end  of 
the  series. 

->  The  length  of  the  DOUBLE  PRECISION  workspace  vector  DSTAK.  LDSTAK 
must  equal  or  exceed  the  appropriate  value  given  below,  where  if 
the  single  precision  version  of  STARPAC  is  being  used  P = 0.5, 
otherwise  P = 1.0.  [See  chapter  1,  § B . ] 

For  DIFC  and  DIFMC : 

NFAC 

LDSTAK  >7+2*  £ [ND(J). IOD(J)] *P 

J=1 

For  GFSLFS  and  GFARFS : 

LDSTAK  > ( 11+10* (9+NF)) /2  + I0-2.NF.P 

where  10  = 0 if  NPRT  = 0,  and  10  = 1 if  NPRT  * 0. 

->  The  length  of  the  vector  PHI.  LPHI  must  equal  or  exceed  IAR. 

— > The  number  of  observations  in  the  time  series.  The  minimum  number 
of  observations  is  three. 

->  The  vector  of  dimension  at  least  NFAC  containing  the  NFAC  values 
designating  the  number  of  times  each  difference  factor  is  to  be 
applied. 

— > The  number  of  frequencies  at  which  the  gain  and  phase  functions 

are  to  be  computed.  The  default  value  is  101.  If  NF  is  not  an 

argument  of  the  subroutine  CALL  statement  the  default  value  is 
used. 
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NFAC  — > The  number  of  difference  factors. 

NPRT  — > The  argument  controlling  printed  output. 

If  NPRT  < 0,  the  output  consists  of  a plot  of  the  gain  function 

versus  frequency,  where  the  gain  function  is 

expressed  in  decibels  and  is  adjusted  so  that  the 
peak  is  at  zero.  For  GFARFS  only  the  output  also 
includes  a plot  of  the  phase  function  versus 

f requency . 

If  NPRT  = 0,  the  automatic  printout  is  suppressed. 

If  NPRT  > 0,  the  output  consists  of  a log-linear  plot  of  the  gain 

function  versus  frequency.  For  GFARFS  only,  the 
output  also  includes  a plot  of  the  phase  function 
versus  frequency. 

The  default  value  is  -1.  If  NPRT  is  not  an  argument  of  the 
subroutine  CALL  statement  the  default  value  is  used. 

NS  — > The  sample  rate,  1 < NS  < N. 

NYF  <—  The  number  of  observations  in  YF. 

NYS  <—  The  number  of  observations  in  YS. 

PHAS  <—  The  vector  of  dimension  at  least  NF  containing  the  NF  phase 

function  values  over  the  range  FMIN  to  FMAX. 

PHI  — The  vector  of  dimension  at  least  NF  containing  IAR  autoregressive 

or  difference  filter  coefficients.  PHI  must  be  input  to  ARFLT, 
GFARF,  and  GFARFS;  it  is  returned  by  DIFC  and  DIFMC. 

For  DIFC  and  DIFMC  the  difference  filter  coefficients  are  obtained 
by  expanding  the  difference  operator 


NFAC 

II 

J=1 


( i.”Biod(J)^ nd(j)  = 


1 - PHICUB1  - PHI(2)B2  - • ••  - PHI(IAR)BIAR 


where 


B 


is  the  backward  shift  operator. 


defined  by  B1yt 


Yt-i’ 


PHI (i ) 


is  the  i1-*1  difference  filter  coefficient, 
positive  or  negative  integer  if  the  ith 
shift  operator  B1  is  used,  and  zero  if 
backward  shift  operator  is  unused. 


which  will  be  a 
order  backward 
the  i^  order 
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Y 

YF 


YFMISS  < 
YMISS 


— > The  vector  of  dimension  at  least  N containing  the  N observations 
of  the  time  series. 

--  The  vector  of  dimension  at  least  N containing  the  NYF  values  of 
the  filtered  series.  The  filtered  series  will  start  in 
YF ( 1 ) ; YF(NYF+1)  through  YF(N)  will  be  set  to  zero. 

For  symmetric  linear  filters: 

The  filtered  series  obtained  by  applying  a moving  average  filter 
is  defined  by 

K 

YF ( I ) = l H( J ) • Y( I+K-J ) for  1=1,  NYF, 

J=1 


where 

NYF  is  the  number  of  values  in  the  filtered  series, 

NYF  = N - (K-l),  reflecting  the  (K-l)/2  data  points  lost 
from  each  end  of  the  original  series  by  the  filtering 
operation. 

For  autoregressive  or  difference  filters: 

The  filtered  series  obtained  using  an  autoregressive  (or 
difference)  filter  is  computed  by 

IAR 

YF(I)  = Z (I+IAR)  - l [ PHI ( J ) • Z ( I+IAR-J ) ] for  I = 1,  . NYF, 

J=1 


where 

Z is  the  N observation  time  series  being  filtered  which,  for 
ARFLT  is  the  input  series  Y minus  its  mean  and,  for  DIF, 
DIFC,  DIFM  and  DIFMC  is  the  input  series  Y; 

NYF  is  the  number  of  observations  in  the  filtered  series, 
NYF  = N-IAR,  reflecting  the  IAR  data  points  lost  from  the 
beginning  of  the  original  series  by  the  filtering  operation. 


— The  missing  value  code  used  within  the  filtered  series  YF  to 
indicate  that  a value  could  not  be  computed  due  to  missing  data. 

->  The  missing  value  code  used  within  the  input  series  Y to  indicate 
that  an  observation  is  missing. 
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YS 


< — The  vector  of  dimension  at  least  N containing  the  series  formed  by 
sampling  every  NS^  element  of  Y, 

YS ( J)  = Y[ ( J— 1 ) • NS  + 1)  for  J = 1,  NYS, 

where  NYS,  the  number  of  observations  in  the  sampled  series,  is 
returned  by  subroutine  SAMPLE.  The  series  will  start  in  YS(1); 
YS(NYS+1)  through  YS(N)  will  be  set  to  zero. 


E . Computational  Methods 


E. 1 Algorithms 

The  code  for  computing  the  low-pass  filter  coefficients  is  based  on 
subroutine  LOPASS,  listed  on  page  149  of  Bloomfield  [1976],  The  transforms 
used  to  compute  the  gain  function  of  symmetric  filters  and  the  gain  and  phase 
functions  autoregressive  (or  difference)  filters  are  based  on  the  algorithms 
shown  on  pages  311  and  420,  respectively,  of  Jenkins  and  Watts  [1968]. 


E . 2 Computed  Results  and  Printed  Output 

Except  for  the  gain  and  phase  function  subroutines,  STARPAC  digital 
filtering  subroutines  do  not  produce  printed  output.  For  the  gain  and  phase 
function  subroutines,  the  argument  controlling  the  printed  results  is  NPRT  and 
is  discussed  in  §D;  the  output  from  the  gain  and  phase  function  subroutines 
consists  of  line  printer  plots  of  the  gain  and  phase  function  of  the  input 
filter. 


F . Examples 

In  the  example  program  of  figure  F-la,  DIF  is  used  to  filter  the  input 
series  Y;  VP  (documented  in  chapter  2)  is  used  to  display  the  log  of  the 
original  series  and  the  differenced  series;  and  GFARF  is  used  to  plot  the  gain 
and  phase  functions  of  the  first  difference  filter.  The  data  used  are  the 
natural  logarithm  of  Series  G,  the  airline  data,  listed  on  page  531  of  Box  and 
Jenkins  [1976] . The  formulas  for  the  gain  and  phase  functions  of  a first 
difference  filter  and  a plot  of  the  corresponding  gain  function  are  shown  on 
pages  296  and  9,  respectively,  of  Jenkins  and  Watts  [1968]. 

Figures  F-lb  and  F-lc  display  the  VP  plot  of  the  log  of  the  original 
series  and  the  differenced  series,  respectively.  Both  plots  have  been 
truncated  so  that  they  will  fit  on  one  page  of  this  manual;  the  actual  plots 
generated  by  VP  continue  for  another  90  lines.  Figures  F-ld  and  F-le  show  the 
output  from  GFARF.  There  is  no  automatic  printout  from  DIF. 
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MAIN  PROGRAM* 


PROGRAM  EXAMPL 


DATA  l 


C 

C 

c 

c 

c 

c 

c 

c 

c 

c 


DEMONSTRATE  DIF  AND  GFARF  USING  SINGLE  PRECISION  VERSION  OF  STARPAC 
RUN  ON  CYBER  180/8*0. 

OUTPUT  UNIT  IS  6 (AUTOMATICALLY  EQUATED  TO  FILE  TA»E6  ON  CYBERS) 

C S EE  CHAPTER  1*  SECTION  D.41 

N.B.  DECLARATION  OF  Y,  YF  AND  PHI  MUST  BE  CHANGED  TO  DOUBLE  PRECISION 
IF  DOUBLE  PRECISION  VERSION  OF  STARPAC  IS  USED. 

REAL  Y (200 ) , YF(200)»  PHI ( 5 ) 

READ  NUMBER  OF  OBSERVATIONS 
OBSERVED  SERIES 


READ  100.  N 

RE  AO  101.  (Y(I),  I-1»N) 

C 

C COMPUTE  LOG  OF  DATA 

C 

00  10  I • 1,  N 

Y ( I ) - AL06 ( Y ( I ) > 

10  CONTINUE 
C 

C CALL  OIF  TO  PERFORM  DIFFERENCING  OPERATION 

C 

CALL  DIF  ( Y , N,  YF,  NYF ) 

C 

C PRINT  TITLE  AND  CALL  VP  TO  DISPLAY  LOG  OF  ORIGINAL  SERIES 


WRITE  (6,  102 1 
CALL  VP  «Y,  N,  1) 

C 

C PRINT  TITLE  AND  CALL  VP  TO  DISPLAY  DIFFERENCED  SERIES 

C 

WRITE  (6,  1031 
CALL  VP  (YF,  NYF,  1) 

C 

C SIT  PARAMETERS  FOR  FIRST  DIFFERENCE  FILTER 

C 

PMim  - i.o 

IAR  « 1 

c 

C PRINT  TITLE  AND  CALL  GFARF  TO  COMPUTE  6AIN  AND  PHASE  OF 

C FIRST  DIFFERENCE  FILTER 

C 

WRITE  (6,  10*1 
CALL  GFARF  (PHI,  IAR) 

C 

STOP 

C 

C FORMAT  STATEMENTS 

C 

100  FORMAT  (415) 

101  FORMAT  (12F6.1) 

102  FORMAT  ( 1 1L06  OF  0RI6INAL  SERIES  DISPLAYED  WITH  STARPAC  PLOT', 

1 • SUBROUTINE  VP') 

103  FORMAT  (URESULTS  OF  STARPAC  FIRST  DIFFERENCE  DIGITAL  FILTERING', 

1 « SUBROUTINE  DIF  DISPLAYED  WITH  STARPAC  PLOT  SUBROUTINE  VP») 

104  FORMAT  C1RESULTS  OF  STARPAC, 

* » GAIN  AND  PHASE  FUNCTION  SUBROUTINE  GFARF') 

END 
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Example  program  using  DIF,  VP  and  GFARF 
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Example  of  partial  VP  output  displaying  the  log  of  the  original  series 
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Example  of  partial  VP  output  displaying  the  differenced  series 


RESULTS  OF  STARRAC  SAIM  AMD  RHASi  FUNCTTOM  SUBROlinMI  GFARF 
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Example  of  GFARF  output  (continued) 


G.  Acknowledgments 

The  code  for  computing  the  low-pass  filter  coefficients  is 
subroutine  LOPASS,  listed  on  page  149  of  Bloomfield  [1976].  The 
used  to  compute  the  gain  function  of  symmetric  filters  and  the  gain 
functions  of  autoregressive  (or  difference)  filters  are  based 
algorithms  shown  on  pages  311  and  420,  res-pectively , of  Jenkins 
[1968]. 
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CHAPTER  11 


COMPLEX  DEMODULATION 


A.  Introduction 


STARPAC  contains  two  subroutines  which  find  the  amplitude  and  phase 
functions  of  a demodulated  series  as  described  in  Bloomfield  [1976] . 

The  demodulated  series  5(t)  is  formed  by  multiplying  the  observed  series 
by  a complex  sinusoid  at  the  demodulation  frequency.  If  the  observed  series  Y 
is  a sinusoid  of  the  nominal  demodulation  frequency  FD  with  varying  amplitude 
and  phase  plus  noise,  that  is, 

Y(t ) = R(t)  cos(2rFDt  + <J>(t))  + a(t) 

. if  2rFDt  + $(t)l  ~if2irFDt  + <{>(t)) 

= 0.5  R(t ) [ e 1 J + e  *  1 ] + a(t) 

then  the  demodulated  series  may  be  represented  by 
-i2ir  FD 

6 (t ) - e Y(t) 


i<b  ( t ) -i(4irFDt  + cj>(t)l  -i2TTFD 

0.5  R(t)e  + (0.5)R(t)e  + e a(t) 


for  t 

- 1. 

© o • 

N 

is 

the 

i 

is 

the 

FD 

is 

the 

R(t) 

is 

the 

<j>  (t) 

is 

the 

a(t) 

is 

the 

Users 

are 

, N,  where 
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declaration  and  CALL  statements  are  given  in  §C  and  the  subroutine  arguments 
are  defined  in  §D.  The  algorithms  used  and  output  produced  by  these 
subroutines  are  discussed  in  §E.  Sample  programs  and  their  output  are  shown 
in  §F. 


B . Subroutine  Descriptions 

Subroutine  DEMOD  computes  the  smoothed  amplitude  and  phase  components  of 
the  demodulated  series.  The  user  must  specify  the  demodulation  frequency, 
along  with  the  number  of  filter  terms  and  the  cutoff  frequency  which  define 
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the  low-pass  filter  utilized  to  smooth  the  demodulated  series.  Output  from 
DEMOD  consists  of  plots  of  the  amplitude  and  phase  functions.  The  phase 
function  plot  reduces  discontinuities  using  the  method  suggested  by  Bloomfield 
[1976].  As  shown  in  figure  F-lc  this  method  displays  both  the  principle  phase 
value,  which  is  defined  to  lie  in  the  range  —it  to  it,  and  the  principle  phase 
value  plus  or  minus  2tt  , where  the  sign  is  chosen  such  that  the  second  value 
lies  in  the  range  ~2tt  to  2tt  . 

Subroutine  DEMODS  is  the  same  as  DEMOD  except  that  the  computed  amplitude 
and  phase  functions  arc  returned  to  the  user  and  the  printed  output  described 
for  DEMOD  is  optional. 

C . Subroutine  Declaration  and  GALL  Statements 

NOTE;  Argument  definitions  and  sample  programs  are  given  in  §D  and  §F, 
respectively.  The  conventions  used  to  present  the  following  declaration  and 
CALL  statments  are  given  in  chapter  1,  §B  and  §D. 

DEMOD:  Compute  and  plot  the  results  of  a complex  demodulation  of  the  input 

series 

<real>  Y (ji) 

DOUBLE  PRECISION  DSTAK (Idstak) 

COMMON  /CSTAK/  DSTAK 

I 

CALL  DEMOD  (Y,  N,  FD,  FC,  K,  LDSTAK) 


DEMODS:  Compute  and  optionally  plot  the  results  of  a complex  demodulation  of 

the  input  series;  return  amplitude  and  phase  functions  of  demodulated 
series 

<real>  Y(n),  AMPL(n),  PHAS (n) 

DOUBLE  PRECISION  VST MUldstak) 

COMMON  /CSTAK/  DSTAK 

CALL  DEMODS  (Y,  N,  FD,  FC,  K,  AMPL,  PHAS,  NDEM,  NPRT,  LDSTAK) 


D.  Dictionary  of  Subroutine  Arguments  and  COMMON  Variables 

NOTE;  — > indicates  that  the  argument  is  input  to  the  subroutine  and  that 

the  input  value  is  preserved; 

<--  indicates  that  the  argument  is  returned  by  the  subroutine; 

<->  indicates  that  the  argument  is  input  to  the  subroutine  and  that 
the  input  value  is  overwritten  by  the  subroutine; 

— indicates  that  the  argument  is  input  to  some  subroutines  and  is 
returned  by  others; 

***  indicates  that  the  argument  is  a subroutine  name; 

* • • indicates  that  the  variable  is  passed  via  COMMON. 
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AMPL  < 

DSTAK 

FC 

FD 

IERR 

K 


LDSTAK  -■ 


— The  vector  of  dimension  at  least  N-(K-l)  that  contains  the  NDEM 
values  of  the  smoothed  amplitude  function  of  the  observed  series, 
AMPL(I)  = R(t),  where  R(t)  is  defined  in  §A  and  the  index  I is 
computed  as  I = t - (K-l)/2  for  t = (K+l)/2  to  N-(K-l)/2.  The 
stored  values  of  the  amplitude  function  will  start  in  AMPL(l); 
AMPL(NDEM+1)  to  AMPL(N)  will  be  set  to  zero. 

* * The  DOUBLE  PRECISION  vector  in  COMMON  /CSTAK/  of  dimension  at 
least  LDSTAK.  DSTAK  provides  workspace  for  the  computations.  The 
first  LDSTAK  locations  of  DSTAK  will  be  overwritten  during 
subroutine  execution. 

-->  The  cutoff  frequency  for  the  low-pass  filter  in  cycles  per  sample 
interval.  FC  must  lie  between  1/K  and  FD. 

->  The  demodulation  frequency  in  cycles  per  sample  interval.  FD  must 
lie  between  0.0  and  0.5. 

An  error  flag  returned  in  COMMON  /ERRCHK/ . [See  chapter  1,  §D.5.] 
Note  that  using  (or  not  using)  the  error  flag  will  not  affect  the 
printed  error  messages  that  are  automatically  provided  even  when 
the  user  has  suppressed  the  normal  printed  output. 

IERR  = 0 indicates  that  no  errors  were  detected. 

IERR  = 1 indicates  that  improper  input  was  detected. 

->  The  number  of  terms  in  the  low-pass  filter  used  to  extract  the 
amplitude  and  phase  functions.  K must  be  odd.  The  user  must 
choose  the  number  of  filter  terms,  K,  so  that  (FC  - 1/K)  > 0 and 
(FC  + 1/K)  < 0.5.  In  addition,  K must  be  chosen  as  a compromise 
between. 

1)  A sharp  cutoff,  that  is,  1/K  small;  and 

2)  Minimizing  the  number  of  data  points  lost  by  the  filtering 
operations.  ( (K  - 1 ) / 2 data  points  will  be  lost  from  each  end 
of  the  series.) 

■->  The  length  of  the  DOUBLE  PRECISION  workspace  vector  DSTAK.  LDSTAK 
must  equal  or  exceed  the  appropriate  value  given  below,  where  if 
the  single  precision  version  of  STARPAC  is  being  used  P = 0.5, 
otherwise  P = 1.0.  [See  chapter  1,  §B.] 

For  DEMOD: 

LDSTAK  > 10  + ( 3 • N+K ) • P 
For  DEMODS: 

LDSTAK  > 9 + (10- 2* N+K)* P 

where  10  = 0 if  NPRT  = 0 and  10  = 1 if  NPRT  t 0. 
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N — > The  number  of  observations,  which  must  equal  or  exceed  17. 

NDEM  < — ■ The  number  of  observations  in  AMPL  and  PHAS,  NDEM  = N - (K-l). 

NPRT  — > The  variable  controlling  printed  output. 

If  NPRT  = 0,  the  automatic  printout  is  suppressed. 

If  NPRT  t 0,  the  automatic  printout  is  provided. 

The  default  value  is  1.  If  NPRT  is  not  an  argument  of  the 
subroutine  CALL  statement  the  default  value  is  used. 

PHAS  < — The  vector  of  dimension  at  least  NDEM  = N-(K-l)  that  contains  the 

NDEM  primary  values  of  the  smoothed  phase  function  of  the  observed 
series,  PHAS(I)  = <|>(t),  where  <f>(t)  is  defined  in  §A  and  the  index 
I is  computed  as  I = t - ( K- 1 ) / 2 for  t = ( K+ 1 ) / 2 to  N - ( K- 1 ) / 2 . 
The  stored  values  of  the  phase  function  will  start  in  PHAS(l); 
PHAS(NDEM+1)  to  PHAS(N)  will  be  set  to  zero. 

Y — ■ > The  vector  of  dimension  at  least  N that  contains  the  observations 

of  the  time  series. 


E . Computational  Methods 
E. 1 Algorithms 

The  STARPAC  code  for  performing  complex  demodulation  was  adapted  from  the 
subroutines  given  on  pages  147  to  150  of  Bloomfield  [1976].  As  noted  in 
Bloomfield,  the  first  term  of  the  demodulated  series  defined  in  §A  is  centered 
about  zero  frequency  while  the  remaining  two  terms  are  centered  at  frequencies 
FD  and  2FD.  Thus,  the  first  term  can  be  separated  from  the  others  using  the 
low-pass  filter  described  in  chapter  10  (with  FC  » FD/2),  resulting  in  the 
complex  filtered  series 

K 

YF(t)  = l HLP(J).6(t+Km-J) 

J=1 

= a (t ) + i*  8 (t  ) 

i<J>(t) 

= 0. 5«  R(t ) * e for  t = K^,  K^+l , ...,  (N-K^+l), 


where 

K is  the  number  of  filter  terms; 

is  the  midpoint  of  the  filter,  = (K+l)/2; 

HLP(J)  is  the  Jt^1  low-pass  filter  coefficient,  defined  in  chapter  10,  §D; 
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a(t)  is  the  real  part  of  the  filtered  series; 

3(t)  is  the  imaginary  part  of  the  filtered  series. 

The  smoothed  estimates  of  the  amplitude  R and  phase  <j>  functions  can  then  be 
extracted  from  the  filtered  series  using 

R(t)  - 2(a(t)2  + B(t)2)1/2 

and 

A 

cf>(t)  = tan_1(a(t)/B  (t))  . 

Note  that  (K-l)/2  points  have  been  lost  from  each  end  of  the  demodulated 
series  by  the  filtering  operation. 


E . 2 Computed  Results  and  Printed  Output 

The  argument  controlling  the  printed  output,  NPRT,  is  discussed  in  §D. 
The  output  consists  of  plots  of  the  smoothed  amplitude  and  phase  functions, 
and  a list  of  the  demodulation  frequency,  cutoff  frequency  and  number  of  terms 
in  the  low-pass  filter  used  to  smooth  the  demodulated  series. 


F . Example 

In  the  example  program  of  figure  F-la,  DEMOD  is  used  to  estimate  the 
amplitude  and  phase  function  corresponding  to  the  input  series  Y.  The  data 
used  are  the  Wolf  sunspot  numbers  for  the  years  1700  to  1960  as  tabulated  by 
Waldmeier  [1961] . Figure  F-lb  shows  the  plot  of  the  amplitude  function  and 
figure  F-lc  shows  the  plot  of  the  phase  function.  Both  plots  have  been 
truncated  so  that  they  will  fit  on  one  page  of  this  manual;  the  actual  plots 
generated  by  DEMOD  continue  for  another  177  lines.  The  transfer  function  of 
the  low-pass  filter  used  in  this  example  is  shown  in  chapter  10,  figure  B.l-1. 
Further  discussion  of  this  example  can  be  found  on  pages  137  to  141  of 
Bloomfield  [1976]. 
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IAIN  PROGRAM 


PROGRAM  E X AM  PL 


C 

C DEMONSTRATE  DEMOD  USING  SINGLE  PRECISION  VERSION  OF  STARPAC 

C RUN  ON  CYBER  180/9A0. 

C 

C OUTPUT  UNIT  IS  6 (AUTOMATICALLY  EQUATED  TO  FILE  T A PI  6 ON  CYBERS) 

C ESEE  CHAPTER  1#  SECTION  D.A] 

C 

C N.B.  DECLARATION  OF  Y MUST  BE  CHANGED  TO  DOUBLE  PRECISION 

C IF  DOUBLE  PRECISION  VERSION  OF  STARPAC  IS  USED. 

C 

REAL  Y ( 300 ) 

DOUBLE  PRECISION  DSTAM900) 

C 

COMMON  /CSTAK/  DSTAK 

c 

C SPECIFY  NECESSARY  DIMENSIONS 

C 

LDSTAK  = 500 
C 

C READ  NUMBER  OF  OBSERVATIONS 

C OBSERVED  SERIES 

C 

READ  100#  N 

READ  101#  ( Y ( I J # I •!#  N ) 

C 

C SET  DEMODULATION  FREQUENCY 

C CUTOFF  FREQUENCY 

C NUMBER  OF  TERMS  IN  THE  LOW-PASS  FILTER 

C 

FD  « 1.0  7 11.0 

FC  = 1.0  / 22.0 

K » A1 

c 

C PRINT  TITLE  ANO  CALL  DEMOO  FOR  COMPLEX  DEMODULATION  ANALYSIS 

C 

WRITE  (6*  102) 

CALL  DEMOD  (V,  N#  FD#  FC#  K#  LDSTAK) 

C 

STOP 

C 

C FORMAT  STATEMENTS 

C 

100  FORMAT  (15) 

101  FORMAT  (10F7.2) 

102  FORMAT  (URESULTS  OF  STARPAC# 

* « COMPLEX  DEMODULATION  SUBROUTINE  DEMOD* S 

END 
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Figure  F-la 

Example  program  using  DEMOD 
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Example  of  DEM0D  output  (continued) 
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CHAPTER  12 


CORRELATION  AND  SPECTRUM  ANALYSIS 


A.  Introduction 


STARPAC  contains  50  subroutines  for  time  series  correlation  and  spectrum 
estimation.  Both  univariate  and  bivariate  series  can  be  analyzed.  Included 
are  subroutines  that  compute  the  correlation  function  using  the  fast  Fourier 
transform  and  that  accept  time  series  with  missing  observations.  The  user  may 
choose  from  spectrum  analysis  subroutines  implementing  the  classical  Fourier 
transformed  covariance  function  techniques  presented  in  Jenkins  and  Watts 
[1968],  the  autoregressive  or  rational  spectrum  techniques  described  by  Jones 
[1971]  or  the  direct  Fourier  transform  (periodogram)  techniques  discussed  in 
Bloomfield  [1976] . 

Users  are  directed  to  §B  for  a brief  description  of  the  subroutines.  The 
declaration  and  CALL  statements  are  given  in  §C  and  the  subroutine  arguments 
are  defined  in  §D.  The  algorithms  used  and  output  produced  by  these 
subroutines  are  discussed  in  §E.  Sample  programs  and  their  output  are  shown 
in  §F. 


B.  Subroutine  Descriptions 

STARPAC  correlation  and  spectrum  analysis  subroutines  are  divided  into 
seven  families.  For  correlation  analysis  of  univariate  and  bivariate  series 
there  are  two  families  of  subroutines  supporting 

1.  Autocorrelation  Analysis  and 

2.  Cross  Correlation  Analysis. 

For  spectrum  estimation  there  are  four  families  of  subroutines  for  univariate 
series  and  one  family  for  bivariate  series  supporting 

3.  Univariate  Spectrum  Estimation  Using  the  Fourier  Transform  of  the 
Autocorrelation  Function, 

4.  Univariate  Spectrum  Estimation  Using  Autoregressive  Models, 

5.  Univariate  Spectrum  Estimation  Using  the  Direct  Fourier  Transform, 

6.  Univariate  Series  Utilities  and 

7.  Bivariate  Spectrum  Estimation  Using  the  Fourier  Transform  of  the 
Cross  Correlation  Function. 

In  general,  each  family  of  subroutines  has  one  basic  subroutine  which 
performs  the  desired  computations  with  a minimum  of  user  input.  The  other 
subroutines  in  each  family  provide  greater  flexibility  to  the  user  at  the 
price  of  more  input.  The  features  of  these  subroutines  are  indicated  by  the 
suffix  letter(s)  on  the  subroutine  (e.g.,  ACFM  and  BFSFS ) . Not  all  features 
are  available  for  each  family.  Features  which  are  common  to  more  than  one 
family  are  described  here.  Features  which  are  unique  to  a specific  family  are 
described  in  the  subsections  below. 

o Suffix  S indicates  that  the  user  is  allowed  to  specify  various  options 
which  are  preset  in  the  simplest  call  and  that  certain  results  are 
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returned  to  the  user  via  the  subroutine  CALL  statement.  In  the  sub- 

sections that  follow,  the  specific  details  of  this  feature  are 
discussed  individually  for  each  family  of  subroutines. 

• Suffix  M indicates  that  the  series  contains  missing  data.  A missing 
value  code  must  be  used  within  the  series  to  specify  time  points 
without  an  observed  value.  There  is  no  limit  on  the  percentage  of  data 
that  can  be  missing.  However,  because  the  correlation  matrix  computed 
from  a series  with  missing  values  is  not  necessarily  positive  definite, 
the  partial  autocorrelation  function  estimates  and  autoregressive  order 
selection  statistics  are  not  computed  and  caution  must  be  used  in 
interpreting  those  results  which  are  provided.  Analysis  of  time  series 
with  missing  values  is  discussed  in  Jones  [1971], 

• Suffix  F indicates  that  the  covariances  are  computed  using  the 
Singleton  [1969]  fast  Fourier  transform  (FFT).  When  the  number  of 
observations  in  the  series  is  large  this  method  of  computation  is  more 
efficient  than  the  direct  computation  normally  used  by  STARPAC. 
Subroutines  with  an  F suffix  reduce  the  amount  of  workspace  needed  by 
using  the  vector  originally  containing  the  data  as  workspace;  the  data 
must  be  copied  into  another  vector  prior  to  calling  these  subroutines 
if  the  data  are  to  be  preserved.  These  subroutines  automatically 
extend  the  length  of  the  input  series  by  appending  enough  zeros  to  meet 
the  requirements  of  this  FFT  code;  the  length  of  the  vector  used  to 
pass  the  data  to  these  subroutines  must  therefore  equal  or  exceed  the 
extended  series  length,  NFFT,  as  discussed  in  §D. 

® Suffix  V indicates  that  the  user  inputs  the  covariances  rather  than  the 
original  series,  thus  avoiding  a time-consuming  recoraputation  of  the 
covariance  function  if  it  is  already  available,  for  example,  from 
subroutines  ACFS,  ACFFS,  ACFMS , CCFS,  CCFFS  or  CCFMS. 


B . 1 Correlation  Analysis 
B.l.a  Univariate  Series 


Autocorrelation  Analysis.  STARPAC ' s autocorrelation  function  (acf) 
subroutines  compute  and  plot  the  autocorrelation  function  estimates;  compute 
the  large  lag  standard  error  of  the  estimates;  perform  a chi-squared  test  of 
the  null  hypothesis  that  the  series  is  white  noise;  compute  the  partial 
autocorrelation  function  coefficients  estimates;  and,  using  the  modified 
Akaike  information  criterion  [Akaike,  1974] , select  the  order  of  an 
autoregressive  process  which  models  the  series  and  estimate  the  parameters  of 
this  autoregressive  model.  The  user  should  note  that  a purely  autoregressive 
model  may  approximate  the  true  structure  of  the  model  with  an  unnecessarily 
large  number  of  terms.  Such  an  autoregressive  model  must  be  used  with 
discretion  since  the  true  structure  might  actually  be  more  complex  including 
moving  average  components,  harmonic  terms  or  some  mixture  of  deterministic  and 
stochastic  elements.  For  some  purposes,  a purely  autoregressive  approximation 
may  be  useful.  In  other  cases,  careful  model  identification  can  lead  to  the 
discovery  of  more  detailed  structure  of  the  data  or  to  a more  parsimonious 
model. 
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The  simplest  of  the  Autocorrelation  Function  subroutines  is  ACF,  which 
performs  the  basic  analysis  described  in  the  preceding  paragraph.  The  other 
autocorrelation  analysis  subroutines  provide  the  same  basic  analysis  as  ACF 
while  adding  the  features  indicated  above  by  suffixes  S,  M,  F,  MS  and  FS. 

For  the  ACF  family  of  subroutines,  the  suffix  S feature  allows  the  user 
to  indicate: 

1)  the  maximum  lag  value  for  which  the  correlation  function  is  to  be 
computed;  and 

2)  the  amount  of  printed  output. 

The  acf  subroutines  with  suffix  S also  return  the  autocovariance  function 
estimates  and  the  coefficients  of  the  selected  autoregressive  model  to  the 
user  via  the  subroutine  CALL  statement. 

The  ACF  family  of  subroutines  also  includes  subroutine  ACFD,  where  the 
suffix  D indicates  that  the  autocorrelation  analysis  will  be  performed  for  a 
sequence  of  differenced  series.  The  difference  factors  are  provided  by  the 
user.  If  the  number  of  difference  factors,  NFAC,  is  greater  than  one, 
difference  factors  beyond  the  first  are  applied  to  the  input  series  Y(t)  to 
yield  a series  Z(t)  given  by 


NFAC 

Z(t)  = { n (i 
J=2 


fiIOD( J ) j ND( J)| 


Y(t) 


where  the  Bk  indicates  the  backward  shift  operator  defined  by 

Bk  Y(t ) = Y(t-k) 

and  IOD  and  ND  are  defined  in  §D.  If  the  number  of  difference  factors  is 
equal  to  one,  Z(t)  = Y(t).  In  either  case,  the  autocorrelation  analysis  is 
performed  first  on  the  series  Z and  then  on  series  Z with  the  difference 
factor  (l  - applied  1 to  ND(1)  times.  This  produces  ND(1)  + 1 passes 

of  the  basic  ACF  analysis. 


B.l.b  Bivariate  Series 


Cross  Correlation  Analysis.  STARPAC's  cross  correlation  analysis 
subroutines  compute  and  plot  the  cross  correlation  function  coefficients  and 
provide  the  large  lag  standard  error  of  these  estimates.  Subroutine  CCF  is 
the  simplest  of  the  Cross  Correlation  Function  subroutines.  The  other  five 
cross  correlation  analysis  subroutines  provide  the  same  basic  analysis  as  CCF 
while  adding  the  features  indicated  above  by  suffixes  S,  M,  F,  MS  and  FS. 

For  the  CCF  family  of  subroutines,  suffix  S indicates  that  the  analysis 
is  provided  for  each  pair  of  series  of  a multivariate  time  series.  The  suffix 
S feature  also  allows  the  user  to  indicate: 
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1)  the  maximum  lag  value  for  which  the  correlation  function  is  to  be 
computed;  and 

2)  the  amount  of  printed  output. 

In  addition,  the  cross  covariance  function  estimates  are  returned  to  the 
user. 


B . 2 Spectrum  Estimation 
B.2.a  Univariate  Series 


Univariate  Spectrum  Estimation  Using  the  Fourier  Transform  of  the 
Autocorrelation  Function.  The  UFS  (Univariate  Fourier  Spectrum)  subroutine 
family  computes  the  estimated  spectrum  from  the  Fourier  transform  of  the 
autocovariance  function  (acvf)  as  discussed  in  Jenkins  and  Watts  [1968],  The 
spectrum  is  smoothed  using  Parzen  windows  with  the  bandwidth  controlled  either 
by  the  user  or  a window-closing  algorithm.  The  principal  output  from  each  of 
these  subroutines  consists  of  plots  of  the  estimated  spectrum. 

Subroutine  UFS  has  the  simplest  CALL  statement  of  this  family  of 
subroutines.  The  printed  output  consists  of  four  spectrum  plots  with 
successively  narrower  bandwidths.  Each  spectrum  is  displayed  in  decibels  (10 
times  the  base  10  logarithm  of  the  power  spectrum)  scaled  so  that  the  maximum 
value  plotted  is  zero.  The  length  of  the  upper  and  lower  95-percent 
confidence  intervals  and  the  bandwidth  for  each  spectrum  are  shown  on  the 
plots. 


The  other  nine  univariate  Fourier  spectrum  estimation  subroutines  provide 
the  same  basic  analysis  as  UFS  while  adding  the  features  indicated  above  by 
suffixes  S,  M,  F,  V,  FS,  MS,  VS,  MV  and  MVS. 

For  the  UFS  family  of  subroutines,  the  suffix  S feature  allows  the  user 
to  indicate: 

1)  the  number  of  different  window  bandwidths  to  be  used  and  the  lag 
window  truncation  point  for  each; 

2)  the  frequency  range  and  the  number  of  frequencies  for  which  the 
spectrum  is  to  be  computed;  and 

3)  whether  the  plot  is  to  be  in  decibels  or  on  a logarithmic  scale. 

In  addition,  the  spectrum  values  are  returned  to  the  user. 


Univariate  Spectrum  Estimation  Using  Autoregressive  Models.  STARPAC 
Univariate  Autoregressive  Spectrum  estimation  subroutines  (UAS  family) 
approximate  an  input  series  with  an  autoregressive  model  and  compute  the 
corresponding  theoretical  spectrum  for  that  model.  For  comparative  purposes, 
the  plot  of  the  autoregressive  spectrum  is  superimposed  against  a Fourier 
spectrum  plot. 

Subroutine  UAS  is  the  simplest  of  the  autoregressive  spectrum  estimation 
subroutines.  It  uses  the  modified  Akaike  information  criterion  [Akaike,  1974] 
to  select  the  order  of  the  autoregressive  model  to  be  used.  The  autoregress- 
ive coefficients  are  then  computed  from  the  autocovariance  function  using  the 
Levinson-Durbin  recursive  method  [Box  and  Jenkins,  1976]  for  solving  the 
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Yule-Walker  equations.  The  lag  window  truncation  point  used  for  the  Fourier 
spectrum  is  half  the  maximum  truncation  point  which  would  have  been  selected 
by  subroutine  UFS.  [See  §D,  argument  LAGS.]  The  output  consists  of  several 
autoregressive  order  selection  statistics  and  a plot  of  the  autoregressive  and 
Fourier  spectra  in  decibels  (10  times  the  base  10  logarithm  of  the  power 
spectrum)  scaled  such  that  the  maximum  value  plotted  is  zero.  The  bandwidth 

and  the  length  of  the  95-percent  confidence  interval  for  the  Fourier  spectrum 
are  shown  on  the  plot.  This  Fourier  spectrum  and  its  confidence  intervals 
should  be  used  in  interpreting  the  autoregressive  spectrum  since  confidence 
intervals  are  not  computed  by  STARPAC  for  the  autoregressive  spectrum.  (The 
bandwidth  is  not  relevant  to  the  autoregressive  spectrum. ) 

The  other  five  autoregressive  spectrum  subroutines  provide  the  same  basic 
analysis  as  subroutine  UAS  while  adding  the  features  indicated  above  by 
suffixes  S,  F,  V,  FS  and  VS. 

For  the  autoregressive  spectrum  family  of  subroutines,  the  suffix  S 
feature  allows  the  user  to  indicate; 

1)  the  order  of  the  autoregressive  model  to  be  used  for  the  autoregres- 
sive spectrum; 

2)  the  lag  window  truncation  point  to  be  used  for  the  Fourier  spectrum; 

3)  the  frequency  range  and  the  number  of  frequencies  within  this  range 
at  which  the  spectrum  is  to  be  computed;  and 

4)  whether  the  plot  is  to  be  in  decibels  or  on  a logarithmic  scale. 

In  addition,  the  autoregressive  and  Fourier  spectra  are  returned  to  the  user. 
The  user  should  be  cautious  about  using  high  order  models  without  checking 
order  selection  statistics  since  such  models  can  produce  spurious  peaks  in  the 
spectrum. 


Univariate  Spectrum  Estimation  Using  the  Direct  Fourier  Transform.  The 

STARPAC  direct  Fourier  transform  subroutines  (PGM  family)  implement  the 
PeriodoGraM  approach  to  time  series  analysis  discussed  in  Bloomfield  [1976], 
Subroutines  are  included  for  computing  the  raw  periodogram  and  for  computing 
and  plotting  the  integrated  periodogram  (or  cumulative  spectrum). 

Subroutine  PGM  computes  the  periodogram  of  the  series  as  described  for 
argument  PER  in  §D  using  zeros  to  extend  the  length  of  the  input  series. 
Output  consists  of  a plot  of  the  computed  periodogram  in  decibels  (10  times 
the  base  10  logarithm  of  the  periodogram  estimates)  scaled  so  that  the  maximum 
value  plotted  is  zero.  The  input  series  must  be  either  centered  or  tapered  by 
the  user  before  PGM  is  called. 

PGMS  provides  the  same  basic  analysis  as  PGM  but  allows  the  user  to 
indicate: 

1)  whether  zeros  or  the  series  mean  is  used  to  extend  the  series; 

2)  the  length  of  the  extended  series;  and 

3)  the  amount  of  printed  output. 

In  addition,  the  periodogram  values  and  their  frequencies  are  returned  to  the 
user  via  the  subroutine  CALL  statement. 


12-5 


The  integrated  periodogram  subroutine  IPGM  first  subtracts  the  series 
mean  from  the  series,  then  extends  the  input  series  with  zeros  and  finally 
computes  the  normalized  integrated  periodogram.  Output  consists  of  a one-page 
plot  of  the  integrated  periodogram,  accompanied  by  95-percent  contours  for 
testing  the  null  hypothesis  of  white  noise.  The  integrated  periodogram  is 
discussed  in  chapter  8 of  Box  and  Jenkins  [1976]. 

The  other  three  integrated  periodogram-  subroutines  add  the  features 
indicated  by  suffixes  S,  P and  PS.  The  suffix  S option  allows  the  user  to 
control  the  amount  of  printed  output;  the  integrated  periodogram  values  and 
their  corresponding  frequencies  are  also  returned  to  the  user  via  the 
subroutine  CALL  statement.  The  suffix  P option  indicates  that  the  user  inputs 
the  periodogram  rather  than  the  original  series,  thus  avoiding  a 
time-consuming  recomputation  of  the  periodogram  if  it  is  already  available, 
for  example,  from  subroutine  PGMS. 


Utilities . STARPAC  includes  utility  subroutines  for  centering 
(subtracting  the  mean)  and  tapering  the  observed  series,  periodogram  smoothing 
and  for  computing  the  Fourier  coefficients  of  the  series.  These  routines  are 
particularly  useful  when  using  direct  Fourier  techniques  such  as  PGM  and 
IPGM. 


Subroutine  CENTER  subtracts  the  series  mean  from  the  series  and  returns 
the  centered  series.  There  is  no  printed  output. 

Subroutine  TAPER  centers  the  input  series  and  applies  the  split- 
cosine-bell  taper  described  for  argument  YT  in  §D.  The  user  specifies  the 
total  proportion  of  the  series  to  be  tapered.  The  centered  tapered  series  is 
returned  to  the  user  and  can  be  used  as  input  to  subroutine  PGM  or  PGMS. 
There  is  no  printed  output. 

Subroutine  FFTLEN  computes  for  an  observed  series  length,  N,  the  minimum 
extended  series  length,  NFFT,  which  will  meet  the  requirements  of  the 
Singleton  FFT  code.  The  value  of  the  extended  series  length  is  returned  to 
the  user.  There  is  no  printed  output. 

Subroutine  MDFLT  smooths  the  input  periodogram  by  applying  a sequence  of 
modified  Daniell  filters  as  discussed  in  chapter  7 of  Bloomfield  [1976],  The 
filtered  series  is  returned  to  the  user.  There  is  no  printed  output. 
Subroutine  MDFLT  takes  advantage  of  the  symmetry  of  the  periodogram  to  avoid 
losing  values  from  the  ends  of  the  series.  It  should  therefore  not  be  used 
for  input  series  that  are  not  symmetric  about  their  end  values.  Other  digital 
filtering  routines,  such  as  those  described  in  chapter  10,  may  also  be  used 
for  periodogram  smoothing  but  end  effect  losses  will  be  incurred. 

Subroutine  FFTR  computes  the  Fourier  coefficients  of  an  input  series  of 
single  precision  observations.  There  is  no  printed  output. 
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B.2.b  Bivariate  Series 


Bivariate  Spectrum  Estimation  Using  the  Fourier  Transform  of  the  Cross 
Correlation  Function.  The  BFS  (Bivariate  _Fourier  Spectrum)  subroutine  family 
computes  the  estimated  spectrum  from  the  Fourier  transform  of  the  covariance 
function  as  discussed  in  Jenkins  and  Watts  [1968].  The  spectrum  is  smoothed 
using  Parzen  windows  with  the  bandwidth  controlled  either  by  the  user  or  a 
window-closing  algorithm.  The  principal  output  from  each  of  these  subroutines 
consists  of  plots  of  the  squared  coherency  and  phase  components  of  the  cross 
spectrum. 

Subroutine  BFS  provides  the  basic  analysis  with  a brief  CALL  statement. 
The  printed  output  consists  of  four  spectrum  plot  pairs  (a  squared  coherency 
plot  and  a phase  plot)  with  successively  narrower  bandwidths  chosen  by  the 
window-closing  algorithm.  The  upper  and  lower  95-percent  confidence  intervals 
and  the  95-percent  significance  levels  are  shown  on  the  coherency  plots. 

The  other  nine  bivariate  Fourier  spectrum  estimation  subroutines  provide 
the  basic  analysis  described  for  BFS  while  adding  the  features  indicated  above 
by  suffixes  S,  M,  F,  V,  FS,  MS,  VS,  MV  and  MVS. 

For  the  BFS  family  of  subroutines,  the  suffix  S feature  allows  the  user 
to  indicate: 

1)  the  number  of  different  window  bandwidths  to  be  used  and  the  lag 
window  truncation  point  for  each; 

2)  the  frequency  range  and  the  number  of  frequencies  for  which  the 
spectrum  is  to  be  computed;  and 

3)  whether  the  plot  is  to  be  in  decibels  or  on  a logarithmic  scale. 

In  addition,  the  squared  coherency  and  phase  values  are  returned  to  the  user. 

C . Subroutine  Declaration  and  CALL  Statements 

NOTE:  Argument  definitions  and  sample  programs  are  given  in  §D  and  §F, 

respectively.  The  conventions  used  to  present  the  following  declaration  and 
CALL  statments  are  given  in  chapter  1,  §B  and  §D. 

Subroutines  for  Autocorrelation  Analysis 
ACF:  Compute  and  print  a two-part  autocorrelation  analysis  of  a series 

<real>  Y (n) 

1 

CALL  ACF  (Y,  N) 
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ACFS:  Compute  and  optionally  print  a two-part  autoaorr elation  analysis  of 

a series  using  user- supplied  control  values;  return  autocovariance 
function  and  order  and  parameter  estimates  of  selected  autoregressive 
model 

<real>  Y (n),  ACOV ( lagmax+1 ) , PHI {lagmax) 

DOUBLE  PRECISION  DSTAK {Idstak) 

COMMON  / CSTAK/  DSTAK 


CALL  ACFS  (Y,  N,  LAGMAX,  LACOV,  ACOV,  IAR,  PHI,  NPRT , LDSTAK) 


ACFM:  Compute  and  print  a two-part  autocorrelation  analysis  of  a series 

with  missing  observations 

<real>  Y (n) 


CALL  ACFM  (Y,  YMISS,  N) 


ACFMS:  Compute  and  optionally  print  a two-part  autocorrelation  analysis 

of  a series  with  missing  observations  using  user- supplied  control 
values;  return  autocovariance  function 

INTEGER  NLPPA (lagmax+1) 

<real>  Y(n),  ACOV (lagmax+1) 

DOUBLE  PRECISION  DSTAK {Idstak) 

COMMON  /CSTAK/  DSTAK 


CALL  ACFMS  (Y,  YMISS,  N,  LAGMAX,  LACOV,  ACOV,  AMISS,  NLPPA,  NPRT, 
1 LDSTAK) 


ACFF:  Compute  and  print  a two-part  autocorrelation  analysis  of  a series; 

use  FFT  for  computations;  return  autocovariance  function  and  order 
and  parameter  estimates  of  selected  autoregressive  model 

<real>  YFFT{nfft) 

DOUBLE  PRECISION  DSTAK {Idstak) 

COMMON  /CSTAK/  DSTAK 


CALL  ACFF  (YFFT,  N,  LYFFT,  LDSTAK) 
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ACFFS: 


Compute  and  optionally  print  a two-part  autocorrelation  analysis  of 
a series  using  user-supplied  control  values;  use  FFT  for 
computations ; return  autocovariance  function  and  order  and  parameter 
estimates  of  selected  autoregressive  model 

<real>  YFFT (nfft),  A.COV (l agmax+1  ) , ?H.I(lagmax) 

DOUBLE  PRECISION  DSTAK (Idstak) 

COMMON  / CSTAK/  DSTAK 


CALL  ACFFS  (YFFT,  N,  LYFFT,  LDSTAK,  LAGMAX,  LACOV,  ACOV,  IAR,  PHI, 
I NPRT) 


ACFD:  Compute  and  print  a two-part  autocorrelation  analysis  of  a 

differenced  series 

INTEGER  ND (nfac) t lOD(nfac) 

<real>  Y(n) 

DOUBLE  PRECISION  DSTAK {Idstak) 

COMMON  /CSTAK/  DSTAK 


CALL  ACFD  (Y,  N,  LAGMAX,  NFAC,  ND,  IOD,  LDSTAK) 


Subroutines  for  Cross  Correlation  Analysis 

CCF:  Compute  and  print  a two-part  cross  correlation  analysis  of  a pair  of 

series 

<real>  Yl(n),  Y2(rc) 


CALL  CCF  (Yl,  Y2 , N) 


CCFS : Compute  and  optionally  print  a two-part  cross  correlation  analysis 

of  a multivariate  series  using  user-supplied  control  values;  return 
cross  covariance  function 

<real>  YM (n,m),  CCOV (l agmax+1 3 m>  m) 

DOUBLE  PRECISION  DSTAK(ldstak) 

COMMON  /CSTAK/  DSTAK 


CALL  CCFS  (YM,  N,  M,  IYM , LAGMAX,  CCOV,  ICCOV,  JCCOV, 
1 NPRT,  LDSTAK) 
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CCFM: 


CCFMS: 


CCFF: 


CCFFS: 


Compute  and  print  a two-part  cross  correlation  analysis  of  a pair  of 
series  with  missing  observations 

<real>  Yl(n),  Y2(n) 


CALL  CCFM  (Yl,  YMISS1 , Y2,  YMISS2,  N) 


Compute  and  optionally  print  a two-part  cross  correlation  analysis 
of  a multivariate  series  with  massing  observations  using  user- 
supplied  control  values;  return  cross  covariance  function 

INTEGER  NLP  PC  (lagmax+1 3m3m) 

<real>  YM( n3m),  YMMISS(tfz),  CCOV  (l  agmax+1 9m3m) 

DOUBLE  PRECISION  DSTAK (Idstak) 

COMMON  / CSTAK/  DSTAK 


CALL  CCFMS  (YM,  YMMISS,  N,  M,  IYM,  LAGM.AX , CCOV,  CMISS, 
1 ICCOV,  JCCOV,  NLPPC , I NLP PC , JNLPPC , NPRT , LDSTAK) 


Compute  and  print  a two-part  cross  correlation  analysis  of  a pair  of 
series ; use  FFT  for  computations 

<real>  YFFT1 (nfft) , YFFT2 (nfft) 

DOUBLE  PRECISION  DSTAK (Idstak) 

COMMON  /CSTAK/  DSTAK 


CALL  CCFF(YFFT1,  YFFT2 , N,  LYFFT,  LDSTAK) 


Compute  and  optionally  print  a two-part  cross  correlation  analysis 
of  a multivariate  series  using  user- supplied  control  values;  use  FFT 
for  computations;  return  cross  covariance  function 

<real>  YMFFT  (nfft3m),  CCOV  (l  agmax+1 3 m3  m) 

DOUBLE  PRECISION  DSTAK {Idstak) 

COMMON  /CSTAK/  DSTAK 


CALL  CCFFS  (YMFFT,  N,  M,  I YMFFT,  LAGMAX,  CCOV, 
1 ICCOV,  JCCOV,  NPRT,  LDSTAK) 


12-10 


Subroutines  for  Univariate  Spectrum  Estimation 
Using  the  Fourier  Transform  of  the  Autocorrelation  Function 


UFS:  Compute  and  print  a univariate  Fourier  spectrum  analysis  of  a series 

<real>  Y (n) 


CALL  UFS  (Y,  N) 


UFSS : Compute  and  optionally  print  a univariate  Fourier  spectrum  analysis 

of  a series  using  user- supplied  control  values;  return  Fourier 
spectrum  and  corresponding  frequencies 

INTEGER  LAGS (raj) 

<real>  Y(n),  SPCF(n/,raj) , FREQ(n/) 

DOUBLE  PRECISION  DSTAK (Idstak) 

COMMON  /CSTAK/  DSTAK 


CALL  UFSS  (Y,  N,  NW,  LAGS , NF , FMIN,  FMAX , NPRT,  SPCF,  ISPCF, 
1 FREQ,  LDSTAK) 


UFSF:  Compute  and  print  a univariate  Fourier  spectrum  analysis  of  a series ; 

use  FFT  for  computations 

<real>  YFFT (nfft) 

DOUBLE  PRECISION  DSTAK ( Idstak ) 

COMMON  /CSTAK/  DSTAK 


CALL  UFSF  (YFFT,  N,  LYFFT,  LDSTAK) 


UFSFS:  Compute  and  optionally  print  a univariate  Fourier  spectrum  analysis 

of  a series  using  user*- supplied  control  values;  use  FFT  for  computa- 
tions; return  Fourier  spectrum  and  corresponding  frequencies 

INTEGER  LAGS  (nw) 

<real>  YFFT  (nf ft ) , SPCF (nf,nw),  FREQ (nf) 

DOUBLE  PRECISION  DSTAK (Idstak) 

COMMON  /CSTAK/  DSTAK 


CALL  UFSFS  (YFFT,  N,  LYFFT,  LDSTAK,  NW , LAGS,  NF , FMIN,  FMAX,  NPRT, 
1 SPCF,  ISPCF , FREQ) 
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UFSM: 


Compute  and  print  a univariate  Fourier  spectrum  analysis  of  a series 
with  missing  observations 

<real>  Y(n) 


CALL  UFSM  (Y,  YMISS,  N) 


UFSMS:  Compute  and  optionally  print  a univariate  Fourier  spectrum  analysis 

of  a series  with  missing  observations  using  user- supplied  control 
values;  return  Fourier  spectrum  and  corresponding  frequencies 

INTEGER  LAGS (raj) 

<real>  Y (n) , SPCF( nf3nw),  FREQ(nf) 

DOUBLE  PRECISION  DSTAK (Idstak) 

COMMON  /CSTAK/  DSTAK 


CALL  UFSMS  (Y,  YMISS , N,  NW , LAGS , NF , FMIN,  FMAX,  NPRT,  SPCF, 
1 ISPCF , FREQ,  LDSTAK) 


UFSV:  Compute  and  print  a univariate  Fourier  spectrum  analysis  of  a series; 

input  covariances  rather  than  original  series 

<real>  ACO V(lagmax+1) 


CALL  UFSV  (ACOV,  LAGMAX,  N) 


UFSVS:  Compute  and  optionally  print  a univariate  Fourier  spectrum  analysis 

of  a series  using  user-supplied  control  values;  input  covariances 
rather  than  original  series;  return  Fourier  spectrum  and  correspond- 
ing frequencies 

INTEGER  LAGS (nw) 

<real>  kCOV (lagmax+1 ) , SPCF (nf9nw)>  FREQ (nf) 

DOUBLE  PRECISION  DSTAK( Idstak) 

COMMON  /CSTAK/  DSTAK 


CALL  UFSVS  (ACOV,  LAGMAX,  N,  NW , LAGS,  NF,  FMIN,  FMAX, 
1 NPRT,  SPCF,  ISPCF,  FREQ,  LDSTAK) 
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UFSMV : Compute  and  print  a univariate  Fourier  spectrum  analysis  of  a series 

with  missing  observations;  input  covariances  rather  than  original 
series 

INTEGER  WLP PA (l agmax+1 ) 

<real>  ACOV (lagmax+1) 


CALL  UFSMV (ACOV,  NLPPA , LAGMAX,  N) 


UFSMV S:  Compute  and  optionally  print  a univariate  Fourier  spectrum  analysis 

of  a series  with  missing  observations  using  user-supplied  control 
values;  input  covariances  rather  than  original  series;  return  Fourier 
spectrum  and  corresponding  frequencies 

INTEGER  NLPPA (lagmax+1) 

<real>  ACOV {lagmax+1 ) , SPCF (nf,nw),  FREQ (nf) 

DOUBLE  PRECISION  DSTAK( Idstak) 

COMMON  /CSTAK/  DSTAK 


CALL  UFSMV S (ACOV,  NLPPA,  LAGMAX,  N,  NW , LAGS,  NF , FMIN, 
1 FMAX,  NPRT,  SPCF,  ISPCF,  FREQ,  LDSTAK) 


Subroutines  for  Univariate  Spectrum  Estimation  Using  Autoregressive  Models 

UAS : Compute  and  print  a univariate  autoregressive  spectrum  analysis  of  a 

series 

<real>  Y(n) 


CALL  UAS  (Y,  N) 


UAS’S:  Compute  and  optionally  print  a univariate  autoregressive  spectrum 

analysis  of  a series  using  user-supplied  control  values;  return 
autoregressive  and  Fourier  spectrum  and  corresponding  frequencies 

<real>  Y(w),  PHI (lagmax) t SPCF (nf),  SPCA (nf),  FREQ (nf) 

DOUBLE  PRECISION  DSTAK ( Idstak ) 

COMMON  /CSTAK/  DSTAK 


CALL  UASS  (Y,  N,  IAR,  PHI,  LAGMAX,  LAG,  NF , FMIN,  FMAX,  NPRT, 
1 SPCA,  SPCF,  FREQ,  LDSTAK) 
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UASF: 


Compute  and  print  a univariate  autoregressive  spectrum  analysis  of  a 
series;  use  FFT  for  computations 


<real>  YFFT (nfft) 

DOUBLE  PRECISION  DSTAK {Idstak) 
COMMON  / CSTAK/  DSTAK 


CALL  UASF(YFFT,  N,  LYFFT,  LDSTAK) 


UASFS:  Compute  and  optionally  print  a univariate  autoregressive  spectrum 

analysis  of  a series  using  user- supplied  control  values;  use  FFT  for 
computations;  return  autoregressive  and  Fourier  spectrum  and 
corresponding  frequencies 

<real>  YFFT  (nfft),  PHI  (lagmax),  SPCA(nf),  SPCF(nf),  FREQ(rz/) 

DOUBLE  PRECISION  DST AK {Idstak) 

COMMON  /CSTAK/  DSTAK 


CALL  UASFS  (YFFT,  N,  LYFFT,  LDSTAK,  IAR,  PHI,  LAGMAX,  LAG,  NF , FMIN, 
1 FMAX , NPRT,  SPCA,  SPCF , FREQ) 


UASV:  Compute  and  print  a univariate  autoregressive  spectrum  analysis  of  a 

series;  input  covariances  rather  than  original  series 

<real>  ACOV  ( lagmax+1  ) 

% 

CALL  UASV  (ACOV,  LAGMAX,  N) 


UASVS:  Compute  and  optionally  print  a univariate  autoregressive  spectrum 

analysis  of  a series  using  user-supplied  control  values;  input 
covariances  rather  than  original  series;  return  autoregressive  and 
Fourier  spectrum  and  corresponding  frequencies 

<real>  AGO V (lagmax+1  ) , Y (n),  PHI (lagmax) 

<real>  SPCA(n/),  SPCF(nf),  FREQ(nf) 

DOUBLE  PRECISION  DSTAK (Idstak) 

COMMON  /CSTAK/  DSTAK 


CALL  UASVS  (ACOV,  LAGMAX,  Y,  N,  IAR,  PHI,  LAG,  NF , FMIN, 
1 FMAX,  NPRT,  SPCA,  SPCF,  FREQ,  LDSTAK) 
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Subroutines  for  Univariate  Spectrum  Estimation  Using  the 
Direct  Fourier  Transform 


PGM: 


PGMS: 


I PGM: 


IPGMS: 


Compute  and  print  a periodogram  analysis  of  a series ; use  FFT  for 
computations 

<real>  YFFT (nfft) 

DOUBLE  PRECISION  DSTAK (Idstak) 

COMMON  /CSTAK/  DSTAK 

1 

CALL  PGM  (YFFT,  N,  LYFFT,  LDSTAK) 


Compute  and  optionally  print  a periodogram  analysis  of  a series;  use 
FFT  for  computations ; return  periodogram  and  corresponding  frequen- 
cies 

<real>  YFFT  (nfft)  t PER (nf),  FREQ (nf) 

CALL  PGMS  (YFFT,  N,  NFFT,  LYFFT,  IEXTND,  NF , PER,  LPER,  FREQ, 

1 LFREQ,  NPRT) 


Compute  and  print  an  integrated  periodogram  analysis  of  a series; 
use  FFT  for  computations 

<real>  YFFT (nfft) 

DOUBLE  PRECISION  DSTAK (Idstak) 

COMMON  /CSTAK/  DSTAK 


CALL  IPGM  (YFFT,  N,  LYFFT,  LDSTAK) 


Compute  and  optionally  print  an  integrated  periodogram  analysis  of  a 
series;  use  FFT  for  computations;  return  integrated  periodogram  and 
corresponding  frequencies 

<real>  YFFT (nfft),  PERI (nf),  FREQ (nf) 

DOUBLE  PRECISION  VSTAK(ldstak) 

COMMON  /CSTAK/  DSTAK 


CALL  IPGMS  (YFFT,  N,  LYFFT,  LDSTAK,  NF , PERI,  LPERI , FREQ,  LFREQ, 
1 NPRT) 
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IPGMP: 


IPGMPS: 


CENTER: 


TAPER: 


FFTLEN : 


Compute  and  print  an  integrated  periodogram  analysis  of  a series ; 
input  periodogram  rather  than  original  series 

<real>  PER (nf),  FREQ(nf) 

DOUBLE  PRECISION  DSTAK ( Idstak ) 

COMMON  /CSTAK/  DSTAK 

i 

CALL  IPGMP  (PER,  FREQ,  NF , N,  LDSTAK) 


Compute  and  optionally  print  an  integrated  periodogram  analysis  of  a 
series ; input  periodogram  rather  than  original  series;  return  inte- 
grated periodogram  and  corresponding  frequencies 

<real>  PER (nf),  FREQ (nf) , PERI(nf) 

DOUBLE  PRECISION  DSTAK ( Idstak) 

COMMON  /CSTAK/  DSTAK 

S 

CALL  IPGMPS  (PER,  FREQ,  NF,  N,  LDSTAK,  PERI,  NPRT) 


Utility  Subroutines 

Subtract  the  series  mean  from  each  observation  of  a series ; return 
the  centered  series  ( no  printed  output) 

<real>  Y («),  YC(«) 

£ 

CALL  CENTER  (Y,  N,  YC) 


Center  a series  about  its  mean  and  apply  a split-cosine-bell  taper; 
return  the  tapered  series  ( no  printed  output) 

<real>  Y(n),  YT(n) 

S 

CALL  TAPER  (Y,  N,  TAPERP,  YT) 


Compute  the  minimum  extended  series  length  for  using  the  Singleton 
FFT;  return  the  extended  series  length  ( no  printed  output) 

CALL  FFTLEN  (N,  NDIV,  NFFT) 
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MDFLT:  Smooth  a periodogram  by  applying  a sequence  of  modified  Daniell 

filters;  return  the  smoothed  periodogram  (no  printed  output) 

INTEGER  KMD (nk ) 

<real>  PER(n/),  PERF(nf) 

DOUBLE  PRECISION  DSTAK (Idstak) 

COMMON  /CSTAK/  DSTAK 


CALL  MDFLT  (PER,  NF , NK,  KMD,  PERF,  LDSTAK) 


FFTR:  Compute  the  Fourier  coefficients  of  an  input  series  of  REAL  (single 

precision ) observations;  return  the  Fourier  coefficients  (no  printed 
output) 

<r eal>  YFFT(n),  kB(nfft) 


CALL  FFTR  ( YFFT,  N,  NF  FT,  IEXTND,  NF , AB,  LAB) 


Subroutines  for  Bivariate  Spectrum  Estimation  Using  the 
Fourier  Transform  of  the  Cross  Correlation  Function 

BFS:  Compute  and  print  a bivariate  Fourier  spectrum  analysis  of  a pair  of 

series 

<real>  Yl(n),  Y2(n) 


CALL  BFS  (Yl,  Y2,  N) 


BFSS:  Compute  and  optionally  print  a bivariate  Fourier  spectrum  analysis 

of  a pair  of  series  using  user-supplied  control  values;  return 
squared  coherency  and  phase  components  of  the  cross  spectrum  and  the 
corresponding  frequencies 

INTEGER  LAGS (nw) 

<real>  Yl(n),  Y2(n),  CSPC2 (nf,nw),  PHAS (nf,nw),  FRE Q(nf) 

DOUBLE  PRECISION  DSTPK  (Idstak) 

COMMON  /CSTAK/  DSTAK 


CALL  BFSS  (Yl,  Y2,  N,  NW , LAGS,  NF , FMIN,  FMAX , NPRT, 
1 CSPC2,  ICSPC2 , PHAS,  IPHAS,  FREQ,  LDSTAK) 
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BFSF: 


Compute  and  print  a bivariate  Fourier  spectrum  analysis  of  a pair  of 
series ; use  FFT  for  computations 


<real>  YFFT1 (nfft ) , YFFT2(n//t) 
DOUBLE  PRECISION  DSTAK (Idstak) 
COMMON  / CSTAK/  DSTAK 


CALL  BFSF  (YFFT1 , YFFT2 , Ns  LYFFT,  LDSTAK) 


BFSFS:  Compute  and  optionally  print  a bivariate  Fourier  spectrum  analysis 

of  a pair  of  series  using  user- supplied  control  values;  use  FFT  for 
computations ; return  squared  coherency  and  phase  components  of  the 
cross  spectrum  and  the  corresponding  frequencies 

INTEGER  LAGS (nw) 

<real>  YFFT1 (nfft ) , YFFT2(rc//t) , CSPC2(n/,nw) , PHAS (nf,  nw ) , 

1 FREQ  (nf) 

DOUBLE  PRECISION  DST  MH(ldstak) 

COMMON  /CSTAK/  DSTAK 


CALL  BFSFS  (YFFT1 , YFFT2 , N,  LYFFT,  LDSTAK,  NW,  LAGS, 

1 NF,  FMIN,  FMAX,  NPRT,  CSPC2 , ICSPC2 , PHAS,  IPHAS,  FREQ) 


BFSM:  Compute  and  print  a bivariate  Fourier  spectrum  analysis  of  a pair  of 

series  with  missing  observations 

<real>  Yl(n),  Y2(n) 

* 

CALL  BFSM  (Y1 , YMISS1 , Y2,  YMISS2 , N) 


BFSMS:  Compute  and  optionally  print  a bivariate  Fourier  spectrum  analysis 

of  a pair  of  series  with  missing  observations  using  user-supplied 
control  values;  return  squared  coherency  and  phase  components  of  the 
cross  spectrum  and  the  corresponding  frequencies 

INTEGER  LAGS(nw) 

<real>  Yl(n),  Y2(n),  CSPC2(n/,nw ) , PHAS  (n.f,  nw  ) , FREQ (nf) 

DOUBLE  PRECISION  DSTAK (Idstak) 

COMMON  /CSTAK/  DSTAK 


CALL  BFSMS  (Yl,  YMISS1,  Y2,  YMISS2 , N,  NW , LAGS,  NF , FMIN, 
1 FMAX,  NPRT,  CSPC2 , ICSPC2 , PHAS,  IPHAS,  FREQ,  LDSTAK) 
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BFSV:  Compute  and  print  a bivariate  Fourier  speotrum  analysis  of  a pair  of 

series;  input  covariances  rather  than  original  series 

<real>  CCO V (lagmax+1  ,m,m) 


CALL  BFSV  (CCOV,  INDEX 1,  INDEX2 , N,  LAGMAX,  ICCOV,  JCCOV) 


BFSVS : Compute  and  optionally  print  a bivariate  Fourier  speotrum  analysis 

of  a pair  of  series  using  user- supplied  control  values;  input 
oovariances  rather  than  original  series;  return  squared  coherency  and 
phase  components  of  the  cross  spectrum  and  the  corresponding  frequen- 
cies 

INTEGER  LAGS (jiw) 

<real>  CCOV (l agmax+1 , m, m)  , CSPC2 (nf,nw),  PHAS {nf, nw ) , FREQ (nf ) 

DOUBLE  PRECISION  DSTAK (Idstak) 

COMMON  / CSTAK/  DSTAK 


CALL  BFSVS  (CCOV,  INDEX1,  INDEX 2 , N,  ICCOV,  JCCOV, 

1 NW,  LAG,  NF,  FMIN,  FMAX,  NPRT,  CSPC2 , ICSPC2 , PHAS,  IPHAS, 

2 FREQ,  LDSTAK) 


BFSMV : Compute  and  print  a bivariate  Fourier  spectrum  analysis  of  a pair  of 

series  with  missing  observations;  input  covariances  rather  than 
original  series 

INTEGER  WLBVC  (lagmax+l,m,m) 

<real>  CCOV( lagmax+1  ,m,m) 


CALL  BFSMV  (CCOV, 
1 LAGMAX,  ICCOV, 


NLP PC , INDEX 1 , INDEX2,  N, 
JCCOV,  INLPPC , JNLPPC ) 
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BFSMVS:  Compute  and  optionally  print  a bivariate  Fourier  spectrum  analysis 

of  a pair  of  series  with  missing  observations  using  user- supplied 
control  values ; input  covariances  rather  than  original  series;  return 
squared  coherency  and  phase  components  of  the  cross  spectrum  and  the 
corresponding  frequencies 

INTEGER  NLPPC(Z .agmax+1  ,m,m)  y LAGS(nw) 

<real>  CCOV( nsm,m),  CSPC2 (nf,nw),  PHAS (nf,nw),  FRE Q(nf) 

DOUBLE  PRECISION  DSTAK (Idstak) 

COMMON  /CSTAK/  DSTAK 


CALL  BFSMVS  (CCOV,  NLPPC , INDEX 1 , INDEX2,  N,  ICCOV , 

1 JCCOV,  INLPPC,  JNLPPC,  NW,  LAGS,  NF , FMIN,  FMAX , NPRT, 

2 CSPC2 , ICSPC2 , PHAS,  IPHAS,  FREQ,  LDSTAK) 


D.  Dictionary  of  Subroutine  Arguments  and  COMMON  Variables 

NOTES  -->  indicates  that  the  argument  is  input  to  the  subroutine  and  that 
the  input  value  is  preserved; 

<“■•  indicates  that  the  argument  is  returned  by  the  subroutine; 

<->  indicates  that  the  argument  is  input  to  the  subroutine  and  that 
the  input  value  is  overwritten  by  the  subroutine; 

— indicates  that  the  argument  is  input  to  some  subroutines  and  is 
returned  by  others; 

***  indicates  that  the  argument  is  a subroutine  name; 

* ° * indicates  that  the  variable  is  passed  via  COMMON. 

AB  <--  The  vector  of  dimension  at  least  2«NF  that  contains  the  NF  real 

and  the  NF  imaginary  components  of  the  Fourier  coefficients  of  the 
input  series.  The  real  and  imaginary  components  of  the  Fourier 
coefficients  are  returned  in  the  REAL  (single  precision)  array  AB 
stored  such  that  the  real  and  imaginary  parts  of  the  complex 
Fourier  coefficients  are 

AB(2I-1)  + i.AB(2I)  for  1=1,  ...,  NF, 

where 

i is  the  complex  value  (-1)1/2;  and 

NF  is  the  number  of  harmonic  frequencies,  NF  = NFFT/2. 

The  vector  YFFT  used  to  input  the  observed  series  can  also  be  used 
in  place  of  the  vector  AB  to  conserve  storage  space. 

ACOV  — The  vector  of  dimension  at  least  LAGMAX  + 1 that  contains  the 
LAGMAX+1  autocovariance  function  (acvf)  estimates  for  lags  i = 0, 

. . . , LAGMAX.  ACOV  is  returned  from  the  autocorrelation  analysis 
subroutines;  it  is  input  to  the  spectrum  analysis  subroutines. 

— continued  — 
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The  acvf  estimate  for  lag  i,  c(i),  is  defined  by 


N-i 


(N-i).  I [(Y(t)-YHY(t+i)-Y>€(t).S(t+i)] 


c(i)  = c(-i)  = 


t=l 


N-i 

N l [?(t)«C(t+i)] 
t=l 


for  lags  i = 0 to  LAGMAX,  where 

Y is  the  average  of  all  observed  values;  and 

£(t)  is  an  indicator  variable,  defined  by 

£(t)  = 1 if  Y(t)  is  observed  (Y(t)  * YMISS),  and 

C (t)  = 0 if  Y(t)  is  missing  (Y(t)  = YMISS). 

The  acvf  are  stored  in  ACOV  such  that  ACOV(I)  = c(I-l)  for  I = 1, 
. . . , LAGMAX+1.  When  there  are  no  missing  observations  the  above 
formula  for  the  acvf  reduces  to  that  of  the  usual  positive 
definite  acvf  estimator. 

AMISS  <—  The  missing  value  code  used  within  ACOV  to  indicate  that  the 
autocovariance  function  at  a given  lag  could  not  be  computed 
because  of  missing  data. 

CCOV  The  three-dimensional  array  of  dimension  at  least  LAGMAX+1  by  M 

by  M that  contains  the  cross  covariance  function  (ccvf)  estimates. 
CCOV  is  returned  by  the  cross  correlation  analysis  subroutines;  it 
is  input  to  the  spectrum  analysis  subroutines. 

The  ccvf  estimate,  c.si,(i),  for  lag  i between  the  series  stored  in 
the  jcn  and  kcn  column  of  YM  is  defined  by 

Cjk(i)  — ckj 

N-i 

(N-i) • l [(YM(t,j)-YMi)*(YM(t+i,k)-YMk)-?i(t).5k(t+i)] 

= t=l 

N-i 

N-  I [5i(t)-Ck(t+i)] 
t=l 

for  lags  i = 0,  ...,  LAGMAX  and  for  series  j = 1,  ...,  M and  k = 
1 , . . . , M,  where 

YMj  is  the  average  of  all  the  observed  values  for  the  column 

of  YM; 
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Fj(t)  is  an  indicator  variable,  defined  by 

£j(t)  = 1 if  YM(t,j)  is  observed  (YM(t,j)  t YMMISS(J)) 

£j(t)  = 0 if  YM(t , j ) is  missing  (YM(t,j)  = YMMISS(J))  . 

When  there  are  no  missing  observations  the  above  formula  for  the 
ccvf  reduces  to  that  of  the  usual. positive  definite  ccvf  estimator 
and  when  j = k the  above  formula  is  that  of  the  autocovariance 
function  for  the  series® 

The  ccvf  are  stored  in  CCOV  such  that 

CCOV(I,J,K)  = Cjk(i-1)  = ckj (-i+1 ) for  I = 1,  . ..,  LAGMAX+1. 

The  appropriate  formulas  for  the  ccvf  estimates  computed  by  CCF 
and  CCFM  can  be  obtained  by  letting  M = 2 and  by  substituting 
Yl(t)  for  YM(t,l)  and  Y2(t)  for  YM(t,2)  in  the  above. 

CMISS  <—  The  missing  value  code  used  in  CCOV  to  indicate  that  the  cross 
covariance  function  at  a given  lag  could  not  be  computed  because 
of  missing  data. 

CSPC2  <—  The  matrix  of  dimension  at  least  NF  by  NW  that  contains  the 
squared  coherency  component  of  the  cross  spectra  between  two 
series,  designated  j and  k,  respectively.  CSPC2(I,L)  contains  the 
smoothed  squared  coherency  value  for  the  I1"*1  frequency  computed 
using  the  L^  lag  point  specified  in  LAGS.  The  returned  values 
are  expressed  as  shown  below  regardless  of  the  plot  option 
selected. 

The  estimated  smoothed  squared  coherency  component  of  the  cross 
spectrum  is 


COSPEC(I,L)2  + QSPEC(I , L )2 
CSPC2(I,L)  = — 

SPCFj (I,L)*SPCFk(I,L) 

for  I = 1,  . . . , NF  and  L = 1,  . ..,  NW,  where 

COSPEC(I,L)  is  the  smoothed  co-spectra  for  the  L1-*1  lag  point, 


LAGS (L)-l 

COSPEC(I,L)  = EVEN0  + 2 \ {EVEN£  WlU)  cos[  2tt£  (FMIN+A  t )]  } ; 

£ = 1 


QSPEC(X,L) 
point , 


is  the  smoothed  quadrature  spectra  for  the  Lth  lag 

— continued  — 
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LAGS (L)-l 

QSPEC(I,L)  =2  l { ODD^  WL(£)  sin[  2tt £ (FMIN+A x)]  } ; 

£=1 

W^(£  ) is  the  Parzen  lag  window  function  for  the  window, 

defined  by 

W(£)  = 1 £ =0 

W (£)  = 1— 6(  |£  | /LAGS(L)  )2+6(  |£  | /LAGS(L))3  1<  \l  |<  LAGS  (L) /2 

W (£)  = 2[  1— ( | £ | /LAGS(L))]3  LAGS  (L) /2<  | Jl  |<LAGS(L) 

W(£)  =0  LAGS  (L)<  |£  | ; 

A j is  the  frequency  increment, 

At  = 2(1  - 1 ) (FMAX  - FMIN)/(NF  - 1); 

EVEN^  and  ODD^  are  functions  of  CCOV  defined  by 

EVEffy  = CCOV(£+l  ,j  ,k)  + CC0V(£+l,k,j)  for  £ =0,  . ..,  LAGS  (L) 

ODD^  = CCOV(£+l,j,k)  - CC0V(£+l,k,j)  for  £ =0,  . ..,  LAGS (L) ; 

SPCFj(I,L)  and  SPCF^CljL)  are  the  univariate  Fourier  spectrum 
estimates  for  series  j and  k,  respectively,  computed  using  the 
Lth  lag  window  truncation  point.  [See  argument  SPCF.] 

Note  that  the  modifications  necessary  for  series  with  missing  data 
are  included  in  the  computation  of  CCOV. 

DSTAK  •••  The  DOUBLE  PRECISION  vector  in  COMMON  / CSTAK/  of  dimension  at 
least  LDSTAK.  DSTAK  provides  workspace  for  the  computations.  The 
first  LDSTAK  locations  of  DSTAK  will  be  overwritten  during 
subroutine  execution. 

FMAX  • — > The  maximum  frequency,  in  cycles  per  sample  interval,  at  which  the 

spectrum  is  to  be  computed  (0.0  < FMIN  < FMAX  < 0.5).  The  default 
value  is  0.5.  If  FMAX  is  outside  the  range  FMIN  to  0.5  or  is  not 
an  argument  in  the  CALL  statement  the  default  value  is  used. 

FMIN  — > The  minimum  frequency,  in  cycles  per  sample  interval,  at  which  the 

spectrum  is  to  be  computed  (0.0  < FMIN  < FMAX  < 0.5).  The  default 
value  is  0.0.  If  FMIN  is  outside  the  range  0.0  to  FMAX  or  is  not 
an  argument  in  the  CALL  statement  the  default  value  is  used. 

FREQ  The  vector  of  dimension  at  least  NF  that  contains  the  NF  frequency 

values  at  which  the  spectrum  is  computed.  FREQ  is  an  input 
argument  to  subroutines  IPGMP  and  IPGMPS.  The  values  of  FREQ  are 
returned  by  all  other  subroutines  including  it  in  their  CALL 
s tatements. 
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IAR 


The  order  of  the  autoregressive  model  chosen  to  approximate  the 

series  and  the  order  of  the  autoregressive  model  to  be  used  in 
computing  the  autoregressive  spectrum.  IAR  is  returned  by  the 
autocorrelation  subroutines;  it  is  input  to  the  autoregressive 
spectrum  analysis  subroutines. 

For  the  autoregressive  spectrum  subroutines: 


The  order  IAR  of  the  autoregressive  model  must  not  exceed 
LAGMAX.  In  no  case  may  IAR  exceed  N/2. 

If  IAR>0,  the  user  must  supply  the  coefficients  for  the  order 
IAR  autoregressive  model  in  the  vector  PHI.  (These 
coefficients  are  available,  for  example,  from  subrou- 
tine ACFS  and  ACFFS  or  perhaps  from  the  ARIMA  model 
fitting  procedure  discussed  in  chapter  13.) 


If  IAR<0,  the  coefficients  for  the  order  | IAR | autoregressive 
model  will  be  computed  by  the  STARPAC  subroutine  using 
Durbin's  recursive  method. 


If  IAR=0,  the  order  and  model  coefficients  will  be  chosen  using 
the  model  selection  criteria  discussed  below  in  §E.2.b 
and  the  input  value  of  IAR  will  be  overwritten  by  the 
selected  value.  If  the  IAR  = 0 option  is  used  the 
user  must  specify  the  order  with  a variable,  i.e. , 


IAR  =■  0 

CALL  ASPS ( . . . , IAR,  . . .) 


NOT 


CALL  ASPS ( . . . , 0,  . . . ). 

The  latter  will  cause  the  value  of  zero  to  be 
redefined  on  many  computers  including  the  CYBER  840 
and  855. 


ICCOV  — > The  exact  value  of  the  first  dimension  of  CCOV  as  specified  in  the 

calling  program. 

ICSPC2  —>  The  exact  value  of  the  first  dimension  of  CSPC2  as  specified  in 
the  calling  program. 

IERR  ***  An  error  flag  returned  in  COMMON  /ERRCHK/.  [See  chapter  1,  §D.5.] 
Note  that  using  (or  not  using)  the  error  flag  will  not  affect  the 
printed  error  messages  that  are  automatically  provided  even  when 
the  user  has  suppressed  the  normal  printed  output. 

IERR  = 0 indicates  that  no  errors  were  detected. 


IERR  = 1 indicates  that  improper  input  was  detected. 
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IEXTND 

INDEX1 

INDEX 2 

INLPPC 

IOD 

IPHAS 

ISPCF 

XYM 

XYMFFT 

JCCOV 

JNLPPC 

KMD 

LAB 

LACOV 

LAG 


-->  The  indicator  variable  used  to  designate  whether  zero  or  the 
series  mean  is  to  be  used  to  extend  the  series.  If  IEXTND  = 0, 
zero  will  be  used.  If  IEXTND  * 0,  the  series  mean  will  be  used. 

— > The  index  of  the  first  series  used  in  computing  the  cross 

covariance  function,  corresponding  to  the  subscript  j used  in  the 
definition  of  CCOV. 

— > The  index  of  the  second  series  used  in  computing  the  cross 

covariance  function,  corresponding  to  the  subscript  k used  in  the 
definition  of  CCOV. 

— > The  exact  value  of  *the  first  dimension  of  NLPPC  as  specified  in 
the  calling  program. 

-->  The  vector  of  dimension  at  least  NFAC  that  contains  the  NFAC 
values  designating  the  order  of  each  difference  factor. 

-=->  The  exact  value  of  the  first  dimension  of  PHAS  as  specified  in  the 
calling  program. 

-~>  The  exact  value  of  the  first  dimension  of  SPCF  as  specified  in  the 
calling  program. 

— ->  The  exact  value  of  the  first  dimension  of  the  matrix  YM  as 
specified  in  the  calling  program. 

”->  The  exact  value  of  the  first  dimension  of  the  matrix  YMFFT  as 
specified  in  the  calling  program. 

“->  The  exact  value  of  the  second  dimension  of  CCOV  as  specified  in 
the  calling  program. 

-~>  The  exact  value  of  the  second  dimension  of  NLPPC  as  specified  in 
the  calling  program. 

-->  The  vector  of  dimension  at  least  NK  that  contains  the  NK  modified 
Daniell  filter  lengths.  All  values  in  KMD  must  be  even. 

-->  The  length  of  the  vector  AB.  LAB  must  equal  or  exceed  NFFT. 

-->  The  length  of  the  vectors  ACOV  and  NLPPA.  LACOV  must  equal  or 
exceed  LAGMAX  + 1. 

<->  The  lag  window  truncation  point  to  be  used  for  computing  the 
Fourier  spectrum.  The  default  value  is  half  the  maximum 
truncation  point  selected  by  the  algorithm  described  for  the 
default  values  of  LAGS.  If  LAG  Is  not  an  argument  of  the  CALL 
statement  or  if  LAG  is  outside  the  range  [1,  N— 1 ] the  default 
value  will  be  used.  If  the  user  supplied  value  for  LAG  is  less 

— continued  — 
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than  or  equal  to  zero,  the  Input  value  will  be  overwritten  by  the 
selected  value . The  user  must  therefore  specify  the  lag  window 
truncation  point  with  a variable  in  this  case,  i.e. , 

LAG  = 0 

CALL  ASPS ( . . . , LAG,  . . . ) 

NOT 


CALL  ASPS ( . . « , 0,  . . . ). 

The  latter  will  cause  the  value  of  zero  to  be  redefined  on  many 
computers  including  the  CYBER  840  and  855. 


LAGMAX  -->  The  maximum  lag  value  for  which  the  correlation  coefficients  are 
computed.  The  default  value  of  LAGMAX  is  selected  by  STARPAC  as 
follows. 


LAGMAX  = 

100 

if 

301 

< 

N. 

LAGMAX  = 

N/3 

if 

96 

< 

N 

< 

300 

LAGMAX  = 

32 

if 

33 

< 

N 

< 

95 

LAGMAX  =• 

N-l 

if 

N 

< 

32 

If  LAGMAX  is  less  than  or  equal  to  zero  or  if  neither  LAGMAX  nor 
LAGS  is  an  argument  in  the  CALL  statement  the  default  value  is 
used.  When  LAGS  is  an  argument  in  the  CALL  statement,  LAGMAX  is 
the  largest  value  in  LAGS. 

LAGS  — > The  vector  of  dimension  at  least  NW  that  contains  the  NW  lag 

window  truncation  points,  1 < LAGS(i)  < N-l  for  i = 1,  ...  NW.  By 

default,  four  lag  window  truncation  points  are  used.  The  smallest 
lag  window  truncation  point  T]^  is  selected  by  examining  the 
covariance  function.  It  is  chosen  to  be  3/16  times  the  lag  value 
beyond  which  the  covariance  function  remains  less  than  the 

95-percent  confidence  limits  for  white  noise,  although  in  no  case 
is  T^  greater  than  LAGMAX / 8 . The  values  of  the  remaining  lag 

window  truncation  points  are  then  specified  by  T2  = 2»T^, 

T3  = 4®Tj  and  T^  = 8»Tj,  resulting  in  progressively  narrower 

bandwidths.  The  procedure  of  using  progressively  narrower 

bandwidths  to  compute  the  spectrum  of  a given  time  series  is 
called  window  closing.  It  is  discussed  in  Jenkins  and  Watts 
[1968].  If  LAGS  is  not  an  argument  in  the  CALL  statement  the  four 
default  values  are  used. 

LDSTAK  -->  The  length  of  the  DOUBLE  PRECISION  workspace  vector  DSTAK.  LDSTAK 

must  equal  or  exceed  the  appropriate  value  given  below.  In  the 

following  specifications  of  the  value  of  LDSTAK,  if  the  single 
precision  version  of  STARPAC  is  being  used  P = 0.5,  otherwise 
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P = 1.0.  [See  chapter  1,  § B . ] Also,  10  = 0 if  NPRT  = 0 and 

10  = 1 if  NPRT  * 0. 


For  autocorrelation  subroutine 


ACFS : LDSTAK  > 

12  + [ 5 » LAGMAX  + 1 ] • P 

ACFMS : LDSTAK  > 

10.(13  + [6* LAGMAX  + i].p) 

ACFF : LDSTAK  > 

6 + NFFT.P 

ACFFS : LDSTAK  > 

12  + [4* LAGMAX  + NFFT  + 1 ] • P 

ACFD:  LDSTAK  > 

16  + [7* LAGMAX  + N + 2]  • P 

For  cross  correlation  subroutine 


CCFS : LDSTAK  > 

12  + [2*M  + 10. (4. LAGMAX  + 2)]«P 

CCFMS : LDSTAK 

(26+M)/2  + [2«M  + 10. (4* LAGMAX  + 2) ]• P 

CCFF:  LDSTAK  > 

6 + NFFT.P 

CCFFS : LDSTAK  > 

13  + [NFFT  + 2«M  + 10.  (4.  LAGMAX  + 2)]»P 

For  univariate  Fourier  spectrum  subroutine 


UFSS : LDSTAK  > 

[26  + I0» (NF+5) ] / 2 + 

[2. LAGMAX  + 2 + 10*  (2.  NF+10)]  • P 

UFSF : LDSTAK  > 

7 + NFFT.P 

UFSFS : LDSTAK  > 

[26  + 10. (NF+5)]/2  + 

[LAGMAX  + 1 + NFFT  + I0«  (2«  NF+10)]  «P 

UFSMS : LDSTAK  > 

[29  + LAGMAX  + 1 + IO-(NF+5)]/2  + 
[ 2»  LAGSMX  + 2 + 10. (2. NF+10)] • P 

UFSVS:  LDSTAK  > 

[23  + IO.(NF+5)]/2  + 

[LAGMAX  + 1 + 10* (2. NF+10)] »P 

UFSMVS : LDSTAK  > 

[23  + 10* (NF+5) ] / 2 + 

[LAGMAX  + 1 + 10. (2. NF+10)] «P 
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For  autoregressive  spectrum  subroutine 


UASS : 

LDSTAK  > [32  + I0« (2«NF+5)]/2  + 

[ 2 • LAGMAX  + 2 + I A»  ( 3* LAGMAX+1 ) + 

10.  (4.NF+10)]  .P 

UASF : 

LDSTAK  > 7 + NFFT.P 

UASFS : 

LDSTAK  > [32  + I0«  (2-NF.+5)  ] /2  + 

[2* LAGMAX  + 2 + NFFT  + IA. ( 3* LAGMAX+1 ) + 

10.  (4.NF+10)]  *P 

UASVS : 

LDSTAK  > [29  + 10- (2. NF+5) ] /2  + 

[LAGMAX  + 1 + IA* (3. LAGMAX+1)  + 

10.  (4.NF+10)]  »P 

where  IA  = 0 if  IAR  t 0 and  IA  = 1 if  IAR  = 0. 


For  direct 

Fourier  spectrum  subroutine 

PGM: 

LDSTAK  > 9 + NFFT.P 

IPGM: 

LDSTAK  > [123  + NFFT/2]/2  + [2* NFFT  + 206]* P 

IPGMS : 

LDSTAK  > 10.  ([123  + NFFT/2]/2  + [2*  NFFT  + 206].  P) 

IPGMP : 

LDSTAK  > [126  + NF]/2  + [3«NF  + 206]. P 

I PGM. PS : 

LDSTAK  > 10.  ([123  + NF]/2  + [2«NF  + 206].  P) 

For  utility  subroutine 

MDFLT:  LDSTAK  > 7 + NF.P 

For  bivariate  Fourier  spectrum  subroutine 


BFSS ; 

LDSTAK  > [38  + I0*4.NF]/2  + [/.LAGMAX  + 7 + IO«8«NF].P 

BFSF ; 

LDSTAK  > 7 + NFFT.P 

BFSFS : 

LDSTAK  > [38  + IO-4-NFJ/2  + 

[6. LAGMAX  + 6 + NFFT  + IO»  8»NF].P 

BFSMS : 

LDSTAK  > [45  + 4* LAGMAX  + I0.4«NF]/2  + 

[7. LAGMAX  + 7 + 2-NF  + 10*8.  NF]-P 

BFSVS : 

LDSTAK  > [35  + IO»4«NF]/2  + 

[3.  LAGMAX  + 3 + 2»NF  + I0«8«NF].P 

BFSMVS : 

LDSTAK  > [35  + IO-4.NFJ/2  + 

[3. LAGMAX  + 3 + 2.NF  + 10*  8.  NF]»P 

LFREQ  -->  The  length 

of  the  vector  FREQ.  LFREQ  must  equal  or  exceed  NF. 
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LPER 


LPERI 

LYFFT 

M 

N 

ND 

NDIV 

NF 


NFAC 

NFFT 


— > The  length  of  the  vector  PER.  LPER  must  equal  or  exceed  NF. 

— > The  length  of  the  vector  PERI.  LPERI  must  equal  or  exceed  NF. 

— > The  maximum  length  allowed  for  the  extended  series  created  in 
YFFT.  LYFFT  must  equal  or  exceed  the  actual  extended  series 
length,  NFFT.  If  too  small  a value  of  LYFFT  is  used  an  error 
message  giving  the  correct  value  is  generated. 

— > The  number  of  columns  of  data  in  YM. 

— > The  number  of  time  points  in  each  series.  For  the  correlation 
analysis  subroutines  the  minimum  number  of  time  points  is  3;  for 
the  spectrum  analysis  subroutines  the  minimum  number  of  time 
points  is  17. 

— > The  vector  of  dimension  at  least  NFAC  that  contains  the  values 
designating  the  number  of  times  each  difference  factor  is  to  be 
applied. 

— > A required  constant  used  by  FFTLEN  to  determine  the  extended 
series  length.  (See  NFFT.)  NDIV  must  be  two  for  a simple  FFT. 

It  must  be  four  when  the  covariance  function  is  being  computed. 

->  The  number  of  frequencies  at  which  the  spectrum  is  computed. 

For  the  Fourier  and  autoregressive  spectrum  subroutines  and  the 
utility  subroutines: 

NF  is  an  input  argument.  The  default  value  of  NF  is  101.  If  NF 
is  not  an  argument  of  the  CALL  statement  the  default  value  will 
be  used. 

For  the  direct  Fourier  spectrum  subroutines: 

NF  is  returned  by  the  subroutine.  The  returned  value  is  NF  = 
NFFT/2. 

— > The  number  of  difference  factors. 

— The  minimum  extended  series  length  that  meets  the  requirements  of 
the  Singleton  FFT  code.  NFFT  is  returned  by  FFTLEN;  it  must  be 
input  to  PGMS  and  FFTR;  it  is  computed  internally  by  all  of  the 
other  subroutines  using  the  FFT. 

The  extended  length  of  the  series  is 

NFFT  = N + LAGMAX  + K 

where  N is  the  number  of  observations  in  the  series.  K > 2 is 
chosen  so  that  NFFT  is  as  small  as  possible,  NFFT-2  is  divisible 
by  4 and  has  no  prime  factors  greater  than  23,  and  the  product  of 
the  square-free  prime  factors  of  NFFT-2  does  not  exceed  209.  In 
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general,  NFFT  will  be  less  than  N+LAGMAX+100  for  the  correlation, 
Fourier  spectrum  and  autoregressive  spectrum  subroutines.  STARPAC 
subroutine  FFTLEN,  when  called  using  the  sequence 


NK 

NLPPA 


NLPPC 


NPRT 


CALL  FFTLEN (N+LAGMAX,  NDIV,  NFFT) 

with  NDIV  ='  2 when  a simple  FFT  is  to  be  computed  and 

NDIV  = 4 when  the  covariance  function  is  to  be  computed, 

returns  the  value  of  NFFT  that  is  actually  used  by  these 
subroutines. 

— > The  number  of  modified  Daniell  filters  to  be  applied. 

!—  The  vector  of  dimension  at  least  LAGMAX+ 1 that  contains  the 
LAGMAX+1  values  designating  the  number  of  lagged  product  pairs 
used  to  compute  the  autocovariance  function  at  each  lag, 

N-i 

NLPPA(I)  = l [c(t)«C(t+i>]  for  i = 0,  ...»  LAGMAX  and  I = i + 1 , 
t=l 

where  £(t)  = 1 if  Y(t)  * YMISS,  and  £(t)  = 0 if  Y(t)  = YMISS. 

--  The  three-dimensional  array  of  dimension  at  least  LAGMAX+1  by  M by 
M that  contains  the  number  of  lagged  product  pairs  used  to  compute 
the  cross  covariance  function  for  each  pair  of  series  at  each 
lag, 


N-i 

NLPPC(I,J,K)  = l [5j(t)€k(t+i>]  for  i = 0,  . ..,  LAGMAX 
t=0  and  I = i + 1, 

where  the  indices  J and  K correspond  directly  to  the  subscripts  j 
and  k,  respectively,  for  j — 1 , ...,  M and  k = 1,  ...,  M;  and 

5 j (t)  = 1 if  YM(t, j)*YMMISS(j)  and  £j(t)  = 0 if  YM(t , j )=YMMISS(j ) . 

->  The  argument  controlling  printed  output.  In  each  case,  when  NPRT 
is  not  an  argument  in  the  subroutine  CALL  statement  the  default 
value  is  used. 

For  the  correlation  analysis  subroutines: 

If  NPRT  = 0,  the  printed  output  is  suppressed. 

If  NPRT  £ 0,  the  printed  output  is  provided. 

The  default  value  is  NPRT  t 0. 
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For  the  Fourier  and  autoregressive  spectrum  analysis  subroutines: 


NW 


PER 


If  NPRT  < -1,  the  spectra  are  plotted  in  decibels  on  a linear 
scale  adjusted  so  that  the  peak  is  at  zero. 

If  NPRT  = 0,  the  printed  output  is  suppressed. 

If  NPRT  > 1,  the  spectra  are  plotted  on  a log-linear  scale. 

The  default  value  is  NPRT  = -1. 

For  the  periodogram  subroutines: 

If  NPRT  < -2,  the  printed  output  consists  of  a page  plot  of  the 
periodogram  versus  frequency  on  a log-linear 
scale. 

If  NPRT  = -1,  the  printed  output  consists  of  a page  plot  of  the 
periodogram  in  decibels  on  a linear  scale. 

If  NPRT  = 0,  the  printed  output  is  suppressed. 

If  NPRT  = 1,  the  printed  output  consists  of  a vertical  plot  of 

the  periodogram  in  decibels  on  a linear  scale. 
The  vertical  axis  shows  the  frequency  in  the  left 
margin. 

If  NPRT  > 2,  the  printed  output  consists  of  a vertical  plot  of 

the  periodogram  on  a log  scale.  The  vertical  axis 
shows  the  frequency  in  the  left  margin. 

The  default  value  is  NPRT  = -1. 

For  the  integrated  periodogram  subroutines: 

If  NPRT  = 0,  the  printed  output  is  suppressed. 

If  NPRT  * 0,  the  printed  output  is  provided. 

The  default  value  is  NPRT  t 0. 

-->  The  number  of  different  window  bandwidths  to  be  used.  The  default 
value  is  four  for  the  Fourier  spectrum  subroutines  and  one  for  the 
autoregressive  spectrum  subroutines.  When  NW  is  not  an  argument 
of  the  subroutine  CALL  statement  the  default  value  is  used. 

The  vector  of  dimension  at  least  NF  that  contains  the  NF 

periodogram  values.  PER  is  returned  by  subroutine  PGMS;  it  must 
be  input  to  subroutines  IPGMP,  IPGMPS  and  MDFLT.  The  vector  YFFT 
used  to  input  the  observed  series  to  PGMS  can  also  be  used  in 
place  of  the  vector  PER  to  conserve  storage  space.  (The  values  in 
YFFT  will  be  overwritten  even  when  YFFT  is  not  used  in  place  of 
PER.  ) 

— continued  — 


12-31 


The  series  periodogram  is  computed  at  the  harmonic  frequencies 

fk  = k/ (NFFT-2)  for  k = 0,  . ..,  (NFFT-2)/2 

by  a direct  Fourier  transformation  of  the  series  using 

PER(I)  = A(I)2  + B(I)2  for  1=1,  ...,  NF, 

where 

NF  is  the  number  of  harmonic  frequencies  at  which  the  periodogram 
is  computed,  NF  = NFFT/2; 

A(I)  is  the  real  component  of  the  Fourier  coefficient, 

NFFT 

A(X)  = (2/(NFFT-2))  J [YCT(t  )•  cos(  2irt  ( 1-1 ) /(NFFT-2))  ] ; 

t=l 

B(I)  is  the  imaginary  component  of  the.  Fourier  coefficient, 

NFFT 

B(I)  = (2/ (NFFT-2))  J [YCT(t)«sin(  2Trt (1-1 )/ (NFFT-2))  ] ; 

t=l 


YCT(t)  is  the  value  of  the  centered  (or  tapered)  input  series  at 
time  t»  [See  arguments  YC  and  YT„ ] 

PERF  <—  The  vector  of  dimension  at  least  NF  that  contains  the  NF  values  of 
the  periodogram  smoothed  by  applying  a sequence  of  modified 
Daniell  filters  to  the  raw  periodogram.  The  sequence  of  filtered 
series  is 


KMD(£) 

PERF£(I)  = l [h£(j)«PERF£„1(tI)]  for  1 = 1,  ...,  NF 

£ = 1 and  £ = 1 , . . . , NK, 


where 

KMD(£ ) is  the  number  of  terms  in  the  £t51  filter  (KMD(£)  must  be 
even)  ; 

h£  ( j ) is  the  j1-*1  filter  coefficient  of  the  £t^1  filter,  defined  by 
~ [2®KMD(£)j  1 for  j = 1 and  KMD(£) 
h£  (j ) = KMD(£)“1  for  j = 2,  KMD(£)-1; 

PERF£  is  the  periodgram  smoothed  using  the  first  £ filters  (PERFq 
is  the  input  periodogram  and  PERF^k  is  the  series  actually 
returned  to  the  user); 
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tj  is  index  of  PERF^_^  defined  by 

tT  = 2-[I+(KMD(£)/2)-l+j]  l<I<KMD(£)/2 

tj  = I-(KMD(£)/2)-l+j  (KMD(£)/2)+l<I<N-KMD(£  )/2 

tx  = 2N-[I+(KMD(£)/2)+l+j  ] N-(KMD(£)/2)+l<I<N 

PERI  <—  The  vector  of  dimension  at  least  NF  that  contains  the  integrated 
periodogram  values.  The  vector  YFFT  used  to  input  the  observed 
series  to  IPGMS  may  be  used  in  place  of  the  vector  PERI  to 
conserve  storage  space. 

The  integrated  periodogram  is  defined  by 

I 

PERI( I)  = (N®  YVAR)™1  l PER(K)  for  I = 1,  . . . , NF 

K=1 

where 

N _ 2 N 

YVAR  = (N-l)“l  l (Y(t)-Y)  with  Y = N"”1  £ Y(t). 

t=l  t=l 


PHAS  <--  The  matrix  of  dimension  at  least  NF  by  NW  that  contains  the 
smoothed  phase  component  of  the  cross  spectra  between  two  series, 
designated  j and  k,  respectively.  PHAS ( I , L ) contains  the  phase 

value  for  the  Ic^  frequency  computed  using  the  Lt^1  lag  window 
truncation  point  specified  in  LAGS. 


The  estimated  phase  component  of  the  cross  spectrum  is 

QSPEC(I,L)2 
PHAS(I,L)  = 

COSPEC(I,L)2 


for  1=1,  ...,NF  and  L = 1,  NW,  where 

COSPEC(I,L)  is  the  smoothed  co-spectra  for  the  lag  point, 

LAGS ( L ) — 1 

COSPEC(I,L)  = EVENq  +2  l (EVEN£  Wl(£  ) cos[  2tt£  ( FMIN+A  j )]  } ; 

£ = 1 

QSPEC(I,L)  is  the  smoothed  quadrature  spectra  for  the  L*"^  lag 
point, 


QSPEC( I, L ) 


LAGS (L)-l 

2 l {ODDjj  Wl(£)  sin[  2tt£(FMIN+Ai)]  } ; 
£=  1 
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PHI 


SPCA 


Wl(£)  is  the  Parzen  lag  window  function  for  the  L1-^  window, 
defined  by 

w(£)  = 1 i =o 

W(£)  = l-6(  U|/LAGS(L))2+6(  U|/LAGS(L))3  U u l<LAGS(L)/2 

W(£)  = 2[l-(  U|/LAGS(L))]3  LAGS(L)/2<  U |<  LAGS(L) 

W(£)  = 0 LAGS(L)<U  | ; 

Aj  is  the  frequency  increment, 

Ax  = 2 • (I-I) • (FMAX-FMIN)/ (NF-1) ; and 
EVEN£  and  ODD£  are  functions  of  CCOV  defined  by 

EVEN£  - CC0V(£+1, j,k)  + CC0V(£+l,k, j)  for  £ = 0,  . ..,  LAGS(L) 
0DD£  = CC0V(£+1,  j,k)  - CCOV ( £+1 ,k, j)  for  £ = 0,  LAGS(L) . 

— The  vector  of  dimension  at  least  LAGMAX  that  contains  the  IAR 
coefficients  of  the  order  IAR  autoregressive  model.  PHI  is 

returned  by  the  autocorrelation  subroutines;  it  is  input  or 
returned  by  the  autoregressive  spectrum  estimation  subroutines 
depending  on  the  value  of  IAR. 

<-•“  The  vector  of  dimension  at  least  NF  that  contains  the  NF  values  of 
the  autoregressive  spectrum.  The  autoregressive  spectrum  esti- 
mates are  defined  by 


SPCA(I)  = SIAR2  { 1 1 ~ l PHI(  £ )«e[l  FtUN  + A : )]  |2} 

£=1 


for  1=1,  . ..,  NF,  where 

Star2  is  the  residual  or  one  step  prediction  variance  of  the  order 
IAR  autoregressive  model, 

IAR 

SIAR2  = (N-IAR-D-iNjACOVd)  - J [ PHI (£ ) • AC0V(£+1 ) ] } , 

£=1 

i is  the  complex  value  (-1)1/2;  and 
Aj  is  the  frequency  increment, 

AX  « 2« (!“!)• (FMAX-FMIN)/ (NF-1 ) . 
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SPCF 


TAPERP  - 
Y 

YC  < 


' — ■ The  array  of  dimension  at  least  NF  by  NW  that  contains  the  NF 

values  of  the  Fourier  spectrum  for  each  of  the  NW  lag  windows. 

For  the  autoregressive  spectrum  analysis  subroutines,  NW  = 1 and 

SPCF  may  be  dimensioned  as  a vector  of  length  at  least  NF. 
SPCF(I,L)  contains  the  spectrum  value  for  the  I1"*1  frequency 
computed  using  the  lag  point  (see  arguments  LAG  and  LAGS). 

The  returned  spectrum  values  are  expressed  as  shown  below 

regardless  of  the  plot  option  selected. 

The  estimated  Fourier  spectrum  values  are 

LAGMAX 

SPCF(I,L)  = AC0V(1)  +2  l (ACOVU+1)  Wl(£  ) cos[  2tt£  (FMIN+A  j )]  } 

£ = 1 

for  I = 1,  NF  and  L - 1,  NW,  where 

W^(£  ) is  the  Parzen  lag  window  function  for  the  L*-*1  window, 

defined  by 

W(£)  = 1 £ =0 

W(£)  = l-6(  | £ | /LAGS  (L)  )2+6(  | £ | /LAGS  (L)  )3  1<  |£  |<  LAGS  (L) /2 

W (£)  » 2[  l-(  | £ | /LAGS  (L)  ) ] 3 LAGS  (L) /2< \l  |<  LAGS  (L) 

W (£)  =0  LAG S ( L ) < | £ | ; 

Aj  is  the  frequency  increment, 

Aj  = 2* ( I— 1 ) • ( FMAX-FMI N ) / ( NF- 1 ) . 

Note  that  the  modifications  necessary  for  series  with  missing  data 
are  included  in  the  computation  of  ACOV. 

— > The  total  proportion  of  the  input  data  to  be  tapered  using  a 
split-cosine-bell  taper.  [See  argument  YT. ] If  TAPER  < 0.0,  the 
tapered  series  is  identical  to  the  centered  series,  YC . If 
TAPERP  > 1.0,  a 100-percent  taper  is  applied  to  the  series. 

->  The  vector  of  dimension  at  least  N that  contains  the  N observa- 
tions of  a time  series. 

— The  vector  of  dimension  at  least  N that  contains  the  centered  time 
series.  The  centered  series  is 

YC(t ) = Y(t)  - Y for  t * 1,  ...,  N 

where  Y is  the  mean  of  the  input  series 
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Y 


N 


N_1(  l 

t = l 


Y(t)). 


YFFT  <->  The  vector  of  dimension  at  least  NFFT  containing  the  N 

observations  of  a time  series  to  be  analyzed  using  the  FFT.  The 
length  of  the  vector  YFFT  must  be  greater  than  N to  allow  for 
extending  the  series.  Note  that  the  input  series  is  overwritten 
by  the  FFT  computations. 

YFFT1  <->  The  vector  of  dimension  at  least  NFFT  containing  the  N 

observations  of  the  first  of  a pair  of  series  selected  from  a 
multivariate  time  series  to  be  analyzed  using  the  FFT.  The  length 
of  the  vector  YFFT  must  be  greater  than  N to  allow  for  extending 

the  series.  Note  that  the  input  series  is  overwritten  by  the  FFT 

computations. 

YFFT2  <->  The  vector  of  dimension  at  least  NFFT  containing  the  N 

observations  of  the  second  of  a pair  of  series  selected  from  a 
multivariate  time  series  to  be  analyzed  using  the  FFT.  The  length 
of  the  vector  YFFT  must  be  greater  than  N to  allow  for  extending 

the  series.  Note  that  the  input  series  is  overwritten  by  the  FFT 

computations. 

YM  ->  The  matrix  of  dimension  at  least  N by  M each  of  whose  M columns 

contains  the  N observations  of  a multivariate  time  series. 


YMFFT  <=>  The  matrix  of  dimension  at  least  NFFT  by  M each  of  whose  M columns 
contains  the  N observations  of  a multivariate  time  series  to  be 
analyzed  using  the  FFT.  The  first  dimension  of  the  array  YMFFT 
must  be  greater  than  N to  allow  for  extending  the  series.  Note 
that  the  input  series  are  overwritten  by  the  FFT  computations. 

YMISS  ~“>  The  missing  value  code  used  within  the  input  series  Y to  indicate 
that  an  observation  is  missing. 

YMISS1  ~“>  The  missing  value  code  used  within  the  input  series  Y1  to  indicate 
that  an  observation  is  missing. 

YMISS2  -- > The  missing  value  code  used  within  the  input  series  Y2  to  indicate 
that  an  observation  is  missing. 

YMMISS  -- > The  vector  of  dimension  at  least  M that  contains  the  M missing 
value  codes  (one  for  each  column)  used  within  each  of  the  M series 
contained  in  YM  to  indicate  that  an  observation  is  missing. 

YT  <--  The  vector  of  dimension  at  least  N that  contains  the  tapered  time 

series.  The  tapered  series  is 

YT(t ) = W(t )® YC(t ) for  t = 1,  ...,  N, 


where 


— continued  — 


12-36 


W(t)  is  the  split-cosine-bell  taper  weight  used  at  time  t, 


W(t)  = 0.5»  { l-cos[ir(t-0.5)/m]  } 
W(t)  = 1 

W(t)  = 0.5»  { l-cos[-rr(N-t+0.5)/m].} 


N-m  + 1<  t<  N 


m + 1<  t<  N-m 


1<  t<  m 


with  m computed  such  that  2m/N  = TAPERP  is  the  proportion  of  data 
to  be  tapered.  The  importance  of  tapering  is  discussed  in  chapter 
5 of  Bloomfield  [1976]. 


Y 1 


-->  The  vector  of  dimension  at  least  N that  contains  the  N observa- 
tions of  the  first  series  of  a multivariate  time  series  pair. 


Y2 


— > The  vector  of  dimension  at  least  N that  contains  the  N observa- 
tions of  the  second  series  of  a multivariate  time  series  pair. 


E . Computational  Methods 

E. 1 Algorithms 

E.l.a  Correlation  Analysis 

The  code  for  computing  the  autocovariance  and  cross  covariance  functions 
using  a fast  Fourier  transform  are  based  on  subroutines  written  by  Jones 
[1971].  The  subroutines  which  compute  the  fast  Fourier  transform  and  which 
compute  the  Fourier  transform  of  real  data  are  those  written  by  Singleton 
[1969]  and  the  subroutine  to  compute  the  cosine  transform  was  written  by 
Richard  H.  Jones.  A discussion  of  the  use  of  the  fast  Fourier  transform  for 
computing  the  correlation  function  can  be  found  on  pages  165  to  167  of 
Bloomfield  [1976].  Zeros  are  automatically  appended  to  the  end  of  the  series 
to  meet  the  requirements  of  computing  the  correlation  function  using  an  FFT. 
Correlation  function  subroutines  not  using  the  FFT  compute  the  correlation 
function  directly  using  the  formulas  given  in  §D  for  arguments  ACOV  and  CCOV. 

The  autoregressive  model  coefficients  given  are  the  Yule-Walker  esti- 
mates, computed  as  described  in  Appendix  A3. 2 of  Box  and  Jenkins  [1976].  This 
is  not  a recommended  estimation  procedure  but  rather  a means  of  providing 
starting  values  for  a maximum  likelihood  or  least  squares  estimation  proce- 
dure. Chapter  13  provides  subroutines  for  estimating  the  least  squares  values 
of  the  parameters  of  an  autoregressive  model  using  these  starting  values. 

E.l.b  Spectrum  Analysis 

The  transformation  used  to  compute  the  univariate  Fourier  spectrum  is 
performed  using  the  algorithm  shown  on  page  311  of  Jenkins  and  Watts  [1968], 
modified  to  correspond  to  the  definition  of  the  spectrum  given  for  argument 
SPCF  in  §D.  (The  computed  spectrum  is  half  that  shown  in  Jenkins  and  Watts. ) 
The  bivariate  or  cross  Fourier  spectrum  is  discussed  in  chapters  8 and  9 of 


12-37 


Jenkins  and  Watts.  Smoothed  squared  coherency  and  phase  estimation  are 
discussed  in  detail  on  pages  377-380  of  Jenkins  and  Watts.  The  algorithm  used 
is  described  on  pages  418-420.  The  confidence  interval  and  significance  test 
for  coherency  is  discussed  in  Bloomfield  [1976]  on  pages  224-228.  The 
modifications  necessary  for  series  with  missing  data  are  included  in  the 
computation  of  the  covariance  function  described  in  §D  under  arguments  ACOV 
and  CCOV.  Covariance  function  values  computed  using  a fast  Fourier  transform 
use  the  FFT  code  written  by  Singleton  [1968];  a discussion  of  this  technique 
for  computing  the  covariance  function  can  be  found  on  pages  165  to  167  of 
Bloomfield  [1976].  Subroutines  using  the  FFT  automatically  subtract  the 
series  mean  and  append  zeros  to  the  end  of  the  series  to  meet  the  requirements 
of  computing  the  covariance  function  using  Singleton's  code. 

The  code  for  computing  the  autoregressive  order  selection  statistics  and 
autoregressive  spectrum  estimates  is  based  on  subroutines  written  by  Jones 
[1971],  The  coefficients  PHI(k),  k = 1,  . ..,  IAR  of  the  autoregressive  model 
are  computed  from  the  autocovariance  function  using  the  Levinson-Durbin 
recursive  method  for  solving  the  Yule-Walker  equations  discussed  in  Appendix 
A3.2  of  Box  and  Jenkins  [1976].  The  order  of  the  autoregressive  model 
selected  by  ST  ARP AC  is  that  having  the  lowest  Akaike  final  prediction  error 
[ Akaike , 1974] . 

Subroutines  PGM,  XPGM,  and  IPGMS  automatically  append  zeros  to  the  end  of 
the  series  to  meet  the  length  requirements  of  the  Singleton  FFT  code  [1969], 

Subroutine  PGMS  and  FFTR  do  not  automatically  center  or  extend  the  input 
series.  Centering  and  extending  the  series  by  appending  either  zeros  or  the 
series  mean  must  be  done  by  the  user.  The  resulting  computations  are  wrong  if 
the  extension  does  not  comply  with  the  code  requirements. 

The  subroutines  for  the  split-cosine-bell  taper  and  the  modified  Daniell 
filter  operation  were  adapted  from  subroutines  TAPER  and  MODDAN  given  on  pages 
116  and  178  of  Bloomfield  [1976]. 


E .2  Computed  Results  and  Printed  Output 
Ec2.a  Correlation  Analysis 

The  Autocorrelation  Subroutines.  The  argument  controlling  the  printed 

output,  NPRT,  is  discussed  in  §D.  The  output  from  the  autocorrelation 

analysis  subroutines  includes  summary  statistics  describing  the  input  series; 
the  autocorrelation  function  estimates  and  their  large  lag  standard  errors; 
the  chi-squared  test  statistic  for  white  noise  and  its  significance  level;  the 
partial  autocorrelation  function  estimates;  autoregressive  model  order  selec- 
tion statistics;  and  parameter  estimates  for  the  selected  model.  In  addition, 
plots  are  provided  of  the  autocorrelation  and  partial  autocorrelation  function 
estimates. 

The  estimated  coefficients  of  the  autocorrelation  function  (acf),  r(i), 
are  computed  with  the  formula 

r(i)  = ACOV ( i +1 ) / ACOV ( 1 ) for  lag  i = 1,  ...,  LAGMAX . 
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The  estimated  standard  errors  (SE)  of  the  acf  are  the  large  lag  standard 
errors  discussed  on  pages  34  to  36  of  Box  and  Jenkins  [1976],  The  standard 
error  listed  at  lag  i is  computed  assuming  that  the  acf  is  zero  for  lags 
greater  than  i.  The  formula  is  given  by 


SE [r(i ) ] = SE [r(-i) ] = 


o 1/2 

(N-i)»{(N-i)  + 2»  £ [ (N-i-v)« r ( v)  ]} 

v=l 


N*NLPPA(i+l ) 


for  i = 1,  . ..,  LAGMAX,  where  q is  the  minimum  of  n - i and  i - 1.  The  user 
must  select  the  "correct"  large  lag  standard  error  based  on  whether  the  acf 
estimates  are  compatible  with  the  assumption  that  the  acf  is  zero  for  the 
selected  lag  value  and  beyond.  This  technique  is  intended  primarily  to 
provide  a means  of  selecting  the  largest  lag  value  for  which  the  acf  is 
significantly  different  from  zero  rather  than  to  provide  actual  standard  error 
estimates  for  each  acf.  The  large  lag  standard  error  at  the  selected  lag  is 
valid  for  all  acf  estimates  at  lags  greater  than  or  equal  to  the  selected  lag; 
the  standard  error  estimates  for  lag  values  less  than  the  selected  lag  are 
meaningless. 

As  discussed  on  pages  64-66  of  Box  and  Jenkins  [1976],  the  estimated 
partial  autocorrelation  function  (pacf)  coefficients,  p(i)  for  i = 1,  ..., 
LAGMAX,  are  estimates  of  the  it^1  coefficient  in  an  autoregressive  process  of 
order  i.  Use  of  the  pacf,  in  conjunction  with  the  acf,  to  identify  an 
autoregressive  moving  average  process  is  discussed  on  pages  174-193  of  Box  and 
Jenkins.  It  should  be  noted,  however,  that  the  method  used  to  compute  the 
pacf  [discussed  in  Appendix  A3. 2 of  Box  and  Jenkins]  is  very  sensitive  to 
rounding  errors.  The  pacf  estimates  may  not  be  reliable  if  the  values  of  the 
parameters  are  close  to  the  nonstationarity  boundaries. 

The  order  IAR  of  the  autoregressive  model  selected  for  the  series  is  that 
having  the  lowest  Akaike  final  prediction  error  [Akaike,  1974].  The  modified 
Akaike  information  criteria  (AIC)  is  then  computed  as 

AIC(J)  = N.Loge(FPEj)  for  J = 1,  LAGMAX, 


where 

LAGMAX  is  the  maximum  lag  value  for  which  the  acvf  has  been  estimated  and  is 
therefore  the  maximum  order  of  autoregressive  model  which  can  be 
selected; 

FPEj  is  the  Akaike  final  prediction  error,  normalized  so  the  minimum  final 
prediction  error  is  one,  that  is, 

FPEj  = (Sj2-  (N+J+1))/(SIAR2.  (N+IAR+1))  ; 

2 

Sj  is  the  residual  or  one  step  prediction  variance  of  the  order  J 

autoregressive  model,  computed  as 
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J 

Sj2  = (N-J-1)“1.n*(AC0V(1)  -•  l PHI( £)  «ACOV (£+1)  } ; 

£=1 


c 2 

SIAR  1S 

IAR  is 

N is 

The  AIC  of 


the  residual  or  one  step  prediction  variance  of  the  selected  model; 
the  order  of  the  AR  model  which  produced  the  minimum  AIC; 
the  number  of  observations  in  the  series, 
the  selected  model  order  will  always  be  zero. 


The  partial  F-test  of  the  change  in  the  residual  sum  of  squares  is  a test 
of  the  null  hypothesis  that  the  order  J pacf  is  zero.  The  F-ratio  is  given 
by 

F1,N-J-1  = (ASj2)/Sj2  = (N-1-J)-PHI(J)2/[1-PHX(J)2] 

where 

ASj2  is  the  change  in  the  residual  variance  due  to  the  hypothesis  that 

PHI(J)  = 0 (1  degree  of  freedom), 

ASj2  = Sj.!2  - Sj2; 

S j2  is  the  residual  variance  of  the  order  J autoregressive  model  (N-J-l 

degrees  of  freedom) . 

The  significance  level  of  each  F-ratio  is  also  listed. 


The  Cross  Correlation  Subroutines.  The  argument  controlling  the  printed 
outpuT^  NPRT,  is  discussed  in  §D«  The  output  from  the  cross  correlation 
analysis  subroutines  includes  summary  statistics  describing  the  two  input 
series;  the  cross  correlation  coefficient  estimates  and  their  standard  errors; 
and  a plot  of  the  cross  correlation  estimates. 

The  cross  correlation  function  (ccf)  estimate  for  the  pair  of  series 
stored  in  the  j*"*1  and  columns  of  YM  is 

r jk(i)  = CCOV ( i+1 , j ,k) / (CCOV (1 , j , j) • CCOV (l,k,k))1/2 
for  lag  1=0,  ...,  LAGMAX,  j = 1,  ...,  M,  and  k = 1,  ...,  M,  where 

rjk^1)  = rkj(-i) * 

The  estimated  standard  errors  (SE)  of  the  ccf  are  computed  as 
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SE[rjk(i)]  = SE [rkj (— i) ] 


(N-i)  • { (N-i ) + 2«  l [(N-i-v)Tjj(v)»rkk(v)]}1/2 
v=l 


N*NLPPC(i+l , j ,k) 

for  lag  i = 0,  ...»  LAGMAX  and  for  series  j = 1,  M and  k = 1,  M, 
where  q is  the  smaller  of  N-i  and  i - 1.  This  standard  error  formula 
assumes  that  there  are  no  cross  correlations  between  the  two  series  being 
compared.  It  does  not  assume  the  two  series  are  white  noise,  although  when 
both  series  have  been  prewhitened  the  summed  portion  of  the  equation  is 
approximately  zero  and  the  results  will  approximately  equal  N_1 /2 , which  is 
the  standard  error  assuming  white  noise.  However,  the  importance  of  prewhi- 
tening before  performing  cross  correlation  analysis  is  clear  from  the  above 
equation.  The  presence  of  autocorrelation  in  either  one  or  both  series  can 
cause  a significant  increase  in  the  variance  of  the  cross  correlation 
estimates,  and,  as  shown  in  the  example  on  page  338  of  Jenkins  and  Watts 
[1968] , the  cross  correlation  function  estimates  can  become  quite  unreliable. 
Autocorrelation  in  the  input  series  should  be  suspected  if  the  standard  error 
estimates  computed  by  the  subroutine  are  not  approximately  N_1 /2  . It  is  best 
to  use  ACF  to  routinely  check  for  autocorrelation  in  the  input  series  before 
performing  cross  correlation  analyses  and  to  prewhiten  the  series  when 
necessary.  The  digital  filtering  subroutines  [chapter  10]  or  the  autoregress- 
ive model  subroutines  can  be  used  for  prewhitening  the  input  series  before 
cross  correlation  analysis  is  performed. 


E„2.b  Spectrum  Analysis 

The  Univariate  Fourier  Spectrum  Analysis  Subroutines.  The  argument 
controlling  the  printed  output,  NPRT,  is  discussed  in  §D.  The  output  from  the 
univariate  Fourier  spectrum  analysis  subroutines  consists  of  four  spectrum 
plots  with  successively  narrower  bandwidths.  Each  spectrum  is  plotted 
either  in  decibels  (10  times  the  base  10  logarithm  of  the  power  spectrum), 
scaled  so  that  the  maximum  value  plotted  is  zero,  or  on  a logarithmic  scale. 
The  95-percent  confidence  interval  and  the  bandwidth  for  each  spectrum  are 
shown  on  the  plots. 

The  bandwidth  of  a Parzen  lag  window  with  truncation  point  T is 
approximately  1.85/T  for  T<<N  and  a low  percentage  of  missing  values.  The 
actual  bandwidth  is 

T -1 
BW  = { l [WU)2.(N-|a|  )2/(N*NLPPAOO)]} 
a =-t 

where  W (l ) is  the  Parzen  lag  window  function  defined  in  §D  under  argument 
SPCF.  The  bandwidth  is  indicated  by  the  displayed  ”B  * W”  in  the  upper-right 
portion  of  the  plot. 
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a spectrum  estimate  using  a 


The  effective  degrees  of  freedom  (edf) 
Parzen  lag  window  is 


edf  = 2.BW.N. 


in 


For  large  values  of  N and  a low  percentage  of  missing  values  this  can  be 
approximated  by  3.71»N/T. 


A 95-percent  confidence  interval  for  the  estimated  spectrum  is 


SPCF(I)«edf  SPCF(I).edf 

» — for  I = 1,  . NF, 

2 2 
x edf, 0.975  X edf, 0.025 

2 

where  X e(jf  a is  the  a-percent  point  function  for  a chi-square  distribution 
with  edf  degrees  of  freedom.  Note  that  when  the  logarithm  of  the  spectrum  is 
plotted  this  confidence  interval  has  constant  width  over  frequency  although  it 
is  not  symmetric.  In  this  case,  the  lower  confidence  interval  limit  is 

l°glo[SPCF(I).ed£/X2edf>0>975]  = log10[SPCF(D]  + log10[edfA  edf>0.975] 
and  the  upper  confidence  interval  limit  is 

l°glo[SPCF(I)*edf/X  edf, 0.025]  = log10[SPCF(I)]  + log10[edf/X  edf,0.025] 
for  I = 1 , . . . , NF. 

The  width  of  the  confidence  interval  is  indicated  by  the  displayed 
”°C  * I"  aligned  vertically  in  the  upper-right  portion  of  the  plot.  The 
asterisk  (*)  separates  the  upper  limit  from  the  lower  limit.  The  user  is 
reminded  that  the  confidence  interval  applies  to  individual  frequency  points, 
not  to  the  spectrum  as  a whole. 


The  Autoregressive  Spectrum  Subroutines.  The  argument  controlling  the 
printed  output,  NPRT,  is  discussed  in  §D.  The  output  from  the  autoregressive 
spectrum  analysis  subroutines  consists  of  a plot  of  the  autoregressive  and 
Fourier  spectra  either  in  decibels  (10  times  the  base  10  logarithm  of  the 
power  spectrum)  scaled  such  that  the  maximum  value  plotted  is  zero  or  on  a 
logarithmic  scale.  The  output  also  includes  the  autoregressive  order 
selection  statistics  when  the  user  does  not  supply  the  value  of  the  order  via 
argument  IAR.  The  bandwidth  and  the  length  of  the  95-percent  confidence 
interval  for  the  Fourier  spectrum  are  shown  on  the  plot.  The  bandwidth  is  not 
relevant  to  the  autoregressive  spectrum.  The  Fourier  spectrum  and  its 
confidence  intervals  should  be  used  in  interpreting  the  autoregressive 
spectrum  since  the  confidence  intervals  for  the  autoregressive  spectrum  are 
not  computed. 

The  autoregressive  order  selection  statistics  include  the  modified  Akaike 
information  criteria  (AIC);  the  results  of  a partial  F-test  of  the  change  in 
the  residual  sum  of  squares  with  the  addition  of  the  most  recent 
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autoregressive  parameter;  the  order  of  the  autoregressive  model  selected;  and 
the  Yule-Walker  estimates  of  the  parameters  of  the  selected  model. 

The  modified  Akaike  information  criteria  (AIC)  is 

AIC(J)  = N-loge(FPEj)  for  J = 0,  LAGMAX, 


where 


LAGMAX  is  the  maximum  lag  value  for  which  the  autocovariance  has  been 
computed,  and  is  therefore  also  the  maximum  order  autoregressive  model 
which  can  be  selected; 


FPEj  is  the  Akaike  final  prediction  error,  normalized  so  that  the  minimum 
final  prediction  variance  Sj^r2  is  one,  that  is, 

FPEj  = ( (N-hJ+1)  • Sj2)  / ( (N+IAR+1)  *SIAR2)  ; 


sj2 


is  the  residual  or  one  step  prediction  variance  of  the  order  J model; 


SIAR2 


is  the  residual  or  one  step  prediction  variance  of  the  selected  model; 


IAR  is  the  order  of  the  model  which  produced  the  minimum  AIC,  i.e.,  the 
order  having  the  lowest  Akaike  final  prediction  error  [Akaike, 
1974]. 


The  AIC  of  the  selected  model  order  will  always  be  zero. 


The  partial  F-test  of  the  change  in  the  residual  sum  of  squares  is  a test 
of  the  null  hypothesis  that  the  J*1*1  autoregressive  coefficient  of  the  order  J 
model  is  zero.  The  F-ratio  is  given  by 

fi,n-j-i  = <asj2)/sj2 


where 

ASj2  is  the  change  in  the  residual  variance  due  to  the  hypothesis  that 

PHI(J)  = 0 (one  degree  of  freedom) , 

2 2 2 
ASj  - Sj_;l  - Sj  ; 

Sj2  is  the  residual  variance  of  the  order  J autoregressive  model  (N-J-l 

degrees  of  freedom) . 

The  significance  level  of  each  F-ratio  is  also  listed. 

The  estimated  Fourier  spectrum  and  its  bandwidth  and  confidence  interval 
are  computed  as  described  above. 


The  Direct  Fourier  Transform  Subroutines.  The  argument  controlling  the 
printed  output,  NPRT,  is  discussed  in  §D.  The  output  from  the  periodogram 
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subroutines  consists  of  a plot  of  the  computed  periodogram  displayed  either  in 
decibels  (10  times  the  base  10  logarithm  of  the  periodogram  estimates),  scaled 
so  that  the  maximum  value  plotted  is  zero,  or  on  a logarithmic  scale.  The 
output  from  the  integrated  periodogram  subroutines  consists  of  a one-page  plot 
of  the  integrated  periodogram  accompanied  by  95-percent  confidence  bands  for 
testing  the  null  hypothesis  of  white  noise.  These  bands  are  the 
Kolmogoroff -Smirnov  probability  limits  applicable  to  cumulative  distribution 
functions  [Hald,  1952] . 


The  Bivariate  Fourier  Spectrum.  The  argument  controlling  the  printed 
output,  NPRT,  is  discussed  in  §D.  The  output  from  the  bivariate  Fourier 
spectrum  subroutines  consists  of  four  spectrum  plot  pairs  (a  squared  coherency 
plot  and  a phase  plot)  with  successively  narrower  bandwidths  chosen  by  the 
window-closing  algorithm.  The  95-percent  confidence  intervals  and  the 
95-percent  significance  levels  are  shown  on  the  coherency  plots. 

The  bandwidth  of  a Parzen  lag  window  with  truncation  point  T is 
approximately  3.71»N/T  for  T<<N  and  a low  percentage  of  missing  values.  The 
actual  bandwidth  is 


i.  -i 

BW  = { l [W(k)2(N-|k|  )2/(N«  NLPPC  (k))  ] } . 

k=-T 

NLPPC (k)  is  the  number  of  lagged  product  pairs  used  to  compute  the  covariance 
function  for  lag  k,  that  is 


N~Jk  | 

NLPPC (k)  = I Ci<t)C2Ct:"|k|  ) 
t=l 


where  C(t)  is  an  indicator  variables  £(t)  = 1 if  Y(t)  has  been  observed,  and 
£(t)  = 0 if  Y(t)  is  missing. 


F c Examples 

Autocorrelation  Analysis.  In  the  example  program  of  figure  F-la  ACF  is 
used  to  compute  and  plot  the  autocorrelations,  partial  autocorrelations,  and 
autoregressive  order  selection  statistics  of  the  input  series  Y,  where  the 
data  used  is  the  series  Xj , a simulated  first  order  autoregressive  model  with 
PHI(l)  = 0.6,  listed  on  page  362  in  Jenkins  and  Watts  [1968].  The  correlation 
estimates  for  this  series  are  given  on  page  421  of  Jenkins  and  Watts. 

Figures  F-lb  through  F-le  show  four  pages  of  output  from  ACF.  The  first 
two  pages  are  autocorrelations  and  the  second  two  pages  are  partial 
autocorrelations.  Note  that  for  all  correlation  plots  the  value  of  the 
lag,  i,  is  is  shown  on  the  left  margin  and  the  actual  correlation  coefficients 
are  shown  on  the  right  margin  of  each  of  the  plots. 
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Cross  Correlation  Analysis.  In  the  example  program  of  figure  F-2a  CCF  is 
used  to  compute  and  plot  the  cross  correlations  between  the  first  50  values  of 
the  series  X-^  and  X2  listed  on  page  361  of  Jenkins  and  Watts  [1968]  . The 
correlation  estimates  for  these  series  are  given  on  page  420  of  Jenkins  and 
Watts. 

Figures  F-2b  through  F-2d  show  the  two-part  output  from  CCF.  Note  that 
for  all  correlation  plots  the  value  of  the  lag,  i,  is  shown  on  the  left  margin 
and  the  actual  correlation  coefficients  are  shown  on  the  right  margin  of  each 
of  the  plots. 


Univariate  Fourier  Spectrum  Analysis.  In  the  example  program  of  figure 
F-3a,  UFS  is  used  to  compute  and  plot  the  univariate  Fourier  spectrum 
estimates  for  the  first  50  values  of  the  series  listed  on  page  318  of  Jenkins 
and  Watts  [1968];  the  spectrum  of  this  series  is  shown  for  various  bandwidths 
on  page  270  of  Jenkins  and  Watts  [1968]  . 

Figures  F-3b  through  F-3e  show  the  four  plots  of  the  power  spectrum  (in 
decibels  versus  frequency)  produced  by  UFS.  Each  spectrum  plotted  is  computed 
using  a narrower  bandwidth  than  the  preceding  one.  The  bandwidth,  lag  window 
truncation  point  and  effective  degrees  of  freedom  for  the  spectrum  are  listed 
at  the  top  of  each  page.  The  bandwidth  and  the  95-percent  confidence  interval 
of  the  individual  spectrum  values  are  shown  graphically  on  each  plot. 


Autoregressive  Spectrum  Analysis.  In  the  example  program  of  figure  F-4a, 
UAS  is  used  to  compute  and  plot  the  univariate  autoregressive  and  Fourier 
spectrum  estimates  for  the  first  50  values  listed  on  page  318  of  Jenkins  and 
Watts  [1968]  . The  theoretical  and  Fourier  spectra  of  this  series  are  shown  on 
page  270  of  Jenkins  and  Watts  [1968]  . 

Figures  F-4b  and  F-4c  show  the  two  pages  of  output  produced  by  UAS.  The 
first  page  lists  the  autoregressive  order  selection  statistics  while  the 
second  gives  a plot  of  the  autoregressive  and  Fourier  spectra.  The  bandwidth, 
lag  window  truncation  point  and  effective  degrees  of  freedom  of  the  Fourier 
spectrum  are  listed  at  the  top  of  the  plot.  The  95-percent  confidence 
interval  and  the  bandwidth  of  the  Fourier  spectrum  are  displayed  on  the  plot. 
The  concept  of  bandwidth  does  not  apply  to  the  autoregressive  spectrum  and 
confidence  intervals  for  the  autoregressive  spectrum  are  not  computed. 


Direct  Fourier  Transform  of  a Univariate  Series  and  Utility  Subroutines. 
In  the  example  program  of  figures  F-5a  and  F-5b,  TAPER  is  used  to  center  the 
input  series  and  to  taper  10  percent  of  the  data  at  the  ends  of  the  series 
(5  percent  at  each  end)  and  PGMS  is  used  to  compute  the  raw  periodogram  of  the 
tapered  series.  MDFLT  is  then  used  to  smooth  the  raw  periodogram  returned  by 
PGMS  with  three  applications  of  a modified  Daniell  filter  of  length  eight. 
PPL  (chapter  3)  is  used  to  produce  a log  plot  the  smoothed  periodogram  versus 
frequency.  (VPL  could  also  have  been  used  to  display  the  results.)  The  data 
used  are  the  Wolf  sunspot  numbers  from  1700  to  1960  as  tabulated  by  Waldmeier 
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[1961].  The  raw  and  smoothed  periodograms  of  the  tapered  series  are  shown  on 
pages  95  and  176,  respectively,  of  Bloomfield  [1976]. 

Figure  F-5c  shows  the  raw  periodogram  output  from  PGMS  while  figure  F-5d 
shows  the  smoothed  periodogram.  There  is  no  printed  output  from  TAPER  or 
MDFLT. 


Bivariate  Fourier  Spectrum  Analysis.  In  the  example  program  of  figure 
F-6a  BFS  is  used  to  compute  and  plot  the  cross'  spectrum  for  the  series  Xj  and 
X2  listed  on  page  361  of  Jenkins  and  Watts  [1968].  The  squared  coherency  and 
phase  spectra  for  these  series  are  shown  on  pages  387  and  388  of  Jenkins  and 
Watts.  Figures  F-6b  through  F~6i  show  the  eight  pages  of  output  from  BFS. 
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Autocorrelation  Analysis 


MAIN  PR06RAP* 


AS 068 AW  EXANPL 

e 

C DENONSTRATE  ACF  USXN6  SIN6LI  PRECISION  VERSION  OF  STARPAC 

C RUN  ON  CYBER  116/840. 

C 

C OUTPUT  UNIT  IS  6 ( AUTONATIC AUT  EQUATED  TO  FILE  TAPE6  ON  C TIERS ) 
C f SEE  CHAPTER  1»  SECTION  D.43 

C 

C N.B.  DECLARATION  OF  Y WUST  BE  CHANS! 0 TO  DOUBLE  PRECISION 
C IF  OOUBLE  PRECISION  VERSION  OF  STARPAC  IS  USED. 

C 

REAL  Y(900) 

C 

C READ  NUNBER  OF  OBSERVATIONS 

C OBSERVED  SERIES 

C 

READ  100*  N 

READ  101*  tvm»  I-1#N) 

C 

C PRINT  TITLE  AND  CALL  ACF  FOR  AUTOCORRELATION  ANALYSIS 
C 

WRITE  (6#  102) 

CALL  ACF  <Y»  N) 

C 

STOP 

C 

C FORNAT  STATENENTS 

C 

100  FORNAT  (19) 

101  FORNAT  (10F6.2) 

102  FORNAT  (URESULTS  OF  STARPAC  AUTOCORRELATION  SUBROUTINE  ACF') 

END 
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Figure  F-la 


Example  program  using  ACF 
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Example  of  ACF  output  (continued) 
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Example  of  ACF  output  (continued) 
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Example  of  ACF  output  (continued) 
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Cross  Correlation  Analysis 


MAIN  PROGRAMS  PROGRAM  EXAMPL 

DEMONSTRATE  CCE  USING  SINGLE  PRECISION  VERSION  OF  STARPAC 
RUN  ON  CYBER  180/8*0. 

OUTPUT  UNIT  IS  6 (AUTOMATICALLY  EQUATED  TO  FILE  TAPE*  ON  CYBIRS) 

C SEE  CHAPTER  It  SECTION  0.4] 

N.B.  DECLARATION  OF  YX  AND  Y2  MUST  BE  CHANGED  TO  OOUBLE  PRECISION 
IF  OOUBLE  PRECISION  VERSION  OF  STARPAC  IS  USED. 

RIAL  YH160)*  Y2(100» 

READ  NUMBER  OF  OBSERVATIONS 
SERIES  X 
SERIES  2 

READ  100*  N 

READ  101*  Itinil*  I*1»N! 

READ  161*  ( Y2( I )*  I«I»NI 

PRINT  TITLE  AND  CALL  CCF  FOR  CROSS  CORRELATION  ANALYSIS 

WRITE  (6*  1021 
CALI  CCF  CV1#  Y2»  N) 

STOP 

FORMAT  STATEMENTS 

100  FORMAT  (19) 

101  FORNAT  (12F6.2) 

102  FORNAT  CIRESULTS  OF  STARPAC  CROSS  CORRELATION  SUBROUTINE  CCF') 
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Figure  F-2a 


Example  program  using  CCF 


12-52 


RESULTS  OF  STAR  FAC  CROSS  CORRELATION  SUBROUTINE  CCF 
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Example  of  CCF  output 
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Example  of  CCF  output  (continued) 
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Example  of  CCF  output  (continued) 


Univariate  Fourier  Spectrum  Analysis 


WAIN  PR06RAHJ 

c 

e 

c 

c 

e 

c 

e 

c 

c 

c 

c 

c 

c 

e 


c 

c 

c 


PROGRAM  EXAWPL 

DEMONSTRATE  UFS  USING  SINGLE  PRECISION  VERSION  OF  STARPAC 
RUN  ON  CYBER  160/840* 

OUTPUT  UNIT  IS  6 ( AUTOMATICALLY  EOUATID  TO  FILE  TAPE6  ON  CYBERSI 
{SEE  CHAPTER  1»  SECTION  0*4] 

N.6.  DECLARATION  OF  Y MUST  BE  CHANGE 0 TO  DOUBLE  PRECISION 
IF  DOUBLE  PRECISION  VERSION  OF  STARPAC  IS  USED* 

REAL  Vf 306) 

READ  NUMBER  OF  OBSERVATIONS 
OBSERVED  SERIES 

READ  100*  N 

READ  101*  mil*  I-1*NS 

PRINT  TITLE  AND  CALL  UFS  FOR  UNIVARIATE  FOURIER  SPECTRUM  ANALYSIS 

WRITE  (6*  1021 
CALL  UFS  IT*  N) 


STOP 

C 

C FORMAT  STATEMENTS 

C 

100  FORMAT  (19) 

101  FORMAT  C10F6.2) 

102  FORMAT  I '1RESULTS  OF  STARPAC* 

• • UNIVARIATE  FOURIER  SPECTRUM  ANALYSIS  SUBROUTINE  UFSM 

C 

END 


DATA*  90 
-0.8B 
-2.76 
0.06 
0.14 
”0.8? 


”0®12  ”0.60 
•1*  TT  0.98 
-0,17  -1.01 
1.99  -0.76 
-O.At  0.26 


-1.36  -0.6? 

1.00  -0.70 
-1.04  -0.66 
-l.ee  -1.77 
1.90  2.14 


1.03  2.14  0.39  -1.10  -1.76 

”1.01  -1.30  -0.89  -0.46  1.63 

”1.12  -0.91  -0.71  -0.20  -0.13 
-1*20  0.49  -0.07  -0.63  -0.39 

1.09  0.31  1.07  2.67  2.44 


Figure  F-3a 


Example  program  using  UFS 
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Example  of  UFS  output 
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Example  of  UFS  output  (continued) 


SHOOTMfJJ  FOUIUIB  SPfC?#U«  ~ 

fH  MSNDOM  MB fM  IAS  M!MDe  TRUNCe  8Te=>  32  6 8«®  »fflft90  6 SOP® 
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Autoregressive  Spectrum  Analysis 


MAIN  PR06R AMI 


PR06RAH  EXAMPL 

C 

C DEMONSTRATE  UAS  USING  SINGLE  PRECISION  VERSION  OF  STARPAC 

C RUN  ON  CYBER  180/640. 

C 

C OUTPUT  UNIT  IS  6 (AUTOMATICALLY  EQUATED  TO  FILE  TAPES.  ON  CYIEPSI 
C CSEE  CHAPTER  1*  SECTION  ©.A3 

C 

C N.B.  DECLARATION  OF  Y MUST  BE  CHANGED  TO  DOUBLE  PRECISION 
C IF  DOUBLE  PRECISION  VERSION  OF  STARPAC  IS  USED. 

C 

REAL  Y ( 300) 

C 

C READ  NUMBER  OF  OBSERVATIONS 

C OBSERVED  SERIES 

C 

READ  100*  N 

read  ioi*  mn«  i>i*n) 

c 

C PRINT  TITLE  ANO  CALL  UAS  FOR  UNIVARIATE  AUTOREGRESSIVE  SPECTRUM  ANALYSIS 
C 

WRITE  (6*  102) 

CALL  UAS  (Y*  N) 

C 

STOP 

C 

C FORMAT  STATEMENTS 

C 

100  FORMAT  (IS) 

101  FORMAT  (10F6.2) 

102  FORMAT  (*1RESULTS  OF  STARPAC  * * 

• • UNIVARIATE  AUTOREGRESSIVE  SPECTRUM  ANALYSIS  SUBROUTINE  UAS1) 

END 


DATA! 


90 

-0.88 

-0.12 

-2.76 

-1.77 

0.06 

-0.17 

0.14 

1.99 

—0.87 

-0.62 

-0.89  -1.38 
0.98  1.00 

-1.01  -1.04 
-0.76  -1.08 
0.28  1.90 


-0.07  1.03 

-0.70  -1.01 
—0.66  —1.12 
-1.77  -1.20 
2.14  1.09 


2.14  0.39 

-1.30  -0.89 
-0.91  -0.71 
0.49  -0.07 
0.31  1.07 


-1.10  -1.78 
-0.46  1.63 

-0.20  -0.13 
-0.63  -0.39 
2.67  2.44 


Figure  F-4a 

Example  program  using  UAS 
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Example  of  UAS  output 


FOURIER  SFECTRUN  <♦)  <1*6  KINO,  TRUNC  s FT,"  16  t >«•  »12*9  t £<>F« 
AND  ORDER  t AUTOREGRESSIVE  SFECIRUN  fl.) 


J 
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Example  of  UAS  output  (continued) 


0 0 6^  O 6^  <Tfr  (T&  O fTl  O O O O >f>  <H>>  O O (P^^OOO^OOOO 


Direct  Fourier  Transform  of  a Univariate  Series  and  Utility  Subroutines 


MAIN  PROCRAHl  PR  OCR AH  EXAHPL 

OENONSTRATE  DIRECT  FOURIER  TRANSFORM  SUBROUTINES  USIN6  SINGLE  PRECISION 
VERSION  OF  STARPAC  RUN  ON  CYBER  1BO/SAO. 

OUTPUT  UNIT  IS  6 (AUTOMATICALLY  EQUATED  TO  FILE  TAPE6  ON  CYBERS) 

(SEE  CHAPTER  1#  SECTION  D.A1 

N.B»  DECLARATION  OF  Y,  YFFT*  PER*  FREQ  AND  PEAF  MUST  BE  CHANCED  TO  DOUBLE 
PRECISION  IF  DOUBLE  PRECISION  VERSION  OF  STARPAC  IS  USED. 

REAL  Y(600)»  YFFT(600I*  PER(SOO)*  FREQ(SOO)*  PERF(iOO) 

INTECER  KMD(IO) 

DOUBLE  PRECISION  DSTAKUOOO) 

COMMON  /CSTARS  OSTAK 


SPECIFY  NECESSARY  DIMENSIONS 

IDSTAK  • 1000 
LPER  « 600 
LFREQ  * 300 
LYFFT  e 600 


READ  NUMBER  OF  MODIFIED  DANIEL  FILTERS  TO  BE  APPLIED 
FILTER  IENCTHS 
NUMBER  OF  OBSERVATIONS 
OBSERVED  SERIES 


READ  100*  NK 

READ  100*  (KNDm*  I - 1*  NR) 

READ  ISO*  N 

READ  101*  (Y(I)»  Isi*M) 

CENTER  THE  SERIES  AND  APPLY  A TEN  PERCENT  TAPER  TO  THE  ENOS  OF  THE  DATA 
YAPERP  » 0*10 

CALL  TAPER  «Y»  N*  YAPERP*  YFFT) 

PRINT  TITLE  AND  CALL  PCNS  TO  CONPUTi  PER I060CR AM  OF  TAPERED  ANO 
EXTENDED  SERIES. 


WRITE  $6*  102) 

NFFT  * 914 
IfKTNO  ■ 0 
NPRT  « f-1) 

CALL  PCMS  (YFFT*  N»  NFFT,  LYFFT,  IEXTNO,  NF,  PER*  LPER*  FREQ, 
1 LFREQ*  NPRT) 

APPLY  MODIFIED  OANIELL  FILTERS  TO  SNOOTH  THE  PERIOOOCRAN 

CALL  HDFIT  (PER*  NF*  NR*  RNO*  PERF*  LOST AM) 

PRINT  TITLE  ANO  CALL  PPL  TO  OISPLAY  SNOOTHEO  PERIOOOCRAN 

WRIT!  (6*  103) 

HOC  « 1 

CALL  PPL  (PERF*  FREO*  NF*  ILOC) 

C 

STOP 


C FORMAT  STATEMENTS 

C 


100  FORMAT  (1019) 


101  FORMAT  (10F7.2) 

102  FORMAT  ( 'IRE SUITS  OF  STARPAC 

103  FORMAT  ( '1RESULTS  OF  STARPAC 

* # DISPLAYED  USINC  STARPAC 

END 


PER IOOQGR AM  SUBROUTINE  PGMS • ) 
FILTER  SUBROUTINE  NDFLT •» 

PLOT  SUBROUTINE  PPL') 


Figure  F~5a 


Example  program  using  TAPER,  PGMS,  MDFLT  and  PPL 
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DATA! 


e 


3 

0 8 
261 


9.00 

11.00 

16.00 

23.00 

36.00 

90.00 

29.00 

20.00 

10.00 

6.00 

3.00 

0.00 

0.00 

2.00 

11.00 

27.00 

47.00 

63.00 

60.00 

39.00 

20.00 

26.00 

22.00 

11.00 

21.00 

40.00 

78.00 

122.00 

103.00 

73.00 

47.00 

39.00 

11.00 

9.00 

16.00 

34.00 

70.00 

81.00 

111.00 

101.00 

73.00 

40.00 

20.00 

16.00 

9.00 

11.00 

22.00 

40.00 

60.00 

60.90 

•3.40 

47.70 

47.00 

30.70 

12.20 

9.60 

10.20 

32.40 

47.60 

94.00 

62.90 

8 9.90 

61.20 

49.10 

36.40 

20.90 

11.40 

37.00 

69.80 

106.10 

100.00 

01.60 

66.90 

34.00 

30.60 

7.00 

19.00 

92.90 

194.40 

129.90 

04.00 

60.10 

30.90 

22.00 

10.20 

24.10 

02.90 

132.00 

130.90 

110.10 

09.90 

66.60 

60.00 

46.90 
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0.90 
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6.90 

6.30 

7.10 

39.60 

73.00 

89.10 

70.00 

64.00 

41.00 
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63.90 

93.00 

62.00 
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Figure  F-5b 

Example  program  using  TAPER,  PGMS , MDFLT  and  PPL  (continued) 
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Example  of  PCJMS  output 


ESULTS  Of  STARPAC  FILTER  SUBROUTINE  NDFLT  DISPLAYED  USINS  STARPAC  PLOT  SUBROUTINE  PEL 


[ 
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Example  of  PPL  output  displaying  smoothed  perlodogram 


Bivariate  Fourier  Spectrum  Analysis 


MAIN  PROGRAM 

C 

c 

c 

e 

c 

c 

e 

c 

c 

c 

e 

€ 

e 

e 

e 


e 

e 


PROGRAM  E1AHPI 

DEMONSTRATE  BPS  USING  SINGLE  PRECISION  VERSION  OF  STARPAC 
RUN  ON  CYBER  160/840. 

OUTPUT  UNIT  IS  6 (AUTOMATICALLY  EQUATED  TO  FILE  TAPE  6 ON  CYBERS) 
(SEE  CHAPTER  1*  SECTION  0.41 

N.B.  DECLARATION  OF  Y1  ANO  Y2  MUST  BE  CHANGED  TO  OOUBLE  PRECISION 
IF  OOUBLE  PRECISION  VERSION  OF  STARPAC  IS  USIO. 

REAL  Yl( 100) » Y2C10O) 

READ  NUMBER  OF  OBSERVATIONS 
SERIES  1 
SERIES  2 

READ  100*  N 

READ  101*  fYltlli  I«1#N) 

READ  101#  ( Y2 ( I ) * I»1»N* 

PRINT  TITLE  ANO  CALL  8FS  FOR  BIVARIATE  FOURIER  SPECTRUM  ANALYSIS 


WRITE  (6*  102) 

CALL  BFS  (Yl»  Y2»  N) 

C 

STOP 

€ 

C FORMAT  STATEMENTS 


100  FORMAT  (15) 

101  FORMAT  (12F6.2) 

102  FORMAT  C'lRESULTS  OF  STARPAC •* 

* • BIVARIATE  FOURIER  SPECTRUM  ANALYSIS  SUBROUTINE  BFS') 

END 


DATA* 


100 

-0.88 

-0.16  -1.87 

1.00 

0.70  -0.15 

-1.22 

-2.00  -0.22 

1.02 

0.02  -0.77 

1.18 

2.10  0.17 

-0.12 

-1.88  -1.50 

0.89 

1.71  1.05 

1.92 

0.51  -1.08 

-0.07 

0.24  0.55 

0.79 

1.12  -1.10 

-1©93 

-1.10  -1.75 

0.55 

-1.40  -2.55 

-1.09 

0.90  —0.66 

0.25 

2.18  2.96 

-0.16 

-0.37  -1.39 

-0.05 

0.41  0.15 

1.00 

1.71  0.58 

0.11 

0.00  2.14 

-1.12 

1.18 

2.13 

0.98 

0.11 

-0.15 

o.se 

1.31 

0.71 

0.11 

-0.60 

-0.52 

-0.24 

0.57 

-0.51 

1.54 

1.11 

1.08 

0.15 

-1.04 

0.12 

0.49 

-0.58 

0.17 

-2.16 

-2.19 

-1.75 

-0.62 

-0.14 

0.74 

0.49 

•1.66 

-0.41 

0.56 

-0.95 

0.48 

0.50 

1.56 

-0.16 

-0.39 

-4.19 

-0.71 

-0.96 

2.69 

0.57 

0.29 

1.97 

0.99 

1.94 

1.88 

2.76 

0.56  -0.69 

0.71 

0.69  -1.61 

0.12 

0.46  -1.66 

0.09 

1.21 

1.46 

2.44 

1.02  -0.51 

1.71 

0.79 

1.55 

0.06 

0.11  -2.62 

1.15 

-0.97  -1.61 

•0.16 

1.27 

1.75 

0.70 

0.71 

0.09 

2.16 

-0.24 

0.98 

0.05 

-0.68 

0.24 

•0.12 

1.01 

2.11 

0.16 

0.06  -1.94 

1.10 

0.48  -1.06 

2.18 

1.14 

0.60 

•1.74  -9. 82  -2.36 
-0.44  -1.37  -1.71 
-0.44  -1.54  -0.13 
0.61  0.42  2.16 

-2.44  -2.12  -1.04 
0.89  -0.69  — 1. II 
-1.28  1.07  3.20 

1.14  -0.67  -0.86 

2.44  0.36  -2.10 

0.59  1.54  0.14 

-0.16  -1.95  -0.64 
0.98  -1.26  -0.29 
0.76  0.69  -1.49 

-0.08  0.17  1.00 

-2.26  -2.03  -0.75 
0.91  1.39  0.96 


Figure  F-6a 


Example  program  using  BFS 
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Example  of  BFS  output 
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Example  of  BFS  output  (continued) 
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Example  of  BFS  output  (continued) 
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Example  of  BFS  output 
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Example  of  BFS  output  (continued) 
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Example  of  BFS  output  (continued) 
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Example  of  BFS  output  (continued) 
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The  code  for  computing  the  autocovariance  and  cross  covariance  functions 
using  a fast  Fourier  transform  are  based  on  subroutines  written  by  Jones 
[1971],  The  subroutines  which  compute  the  fast  Fourier  transform  and  which 
compute  the  Fourier  transform  of  real  data  are  those  written  by  Singleton 
[1969]  and  the  subroutine  to  compute  the  cosine  transform  was  written  by 
Jones. 


The  transformation  used  to  compute  the  univariate  Fourier  spectrum  is 
performed  using  the  algorithm  shown  on  page  311  of  Jenkins  and  Watts  [1968]. 
The  algorithm  used  is  described  on  pages  418-420. 

The  code  for  computing  the  autoregressive  order  selection  statistics  and 
autoregressive  spectrum  estimates  is  based  on  subroutines  written  by  Jones 
[1971].  The  coefficients  PHI(k),  k = 1 , ...,  IAR  of  the  autoregressive  model 
used  by  the  autoregressive  spectrum  subroutines  are  computed  from  the 
autocovariance  function  using  the  Levinson-Durbin  recursive  method  for  solving 
the  Yule-Walker  equations  discussed  in  Appendix  A3. 2 of  Box  and  Jenkins 
[1976] . 

The  subroutines  for  the  split-cosine-bell  taper  and  the  modified  Daniell 
filter  operation  were  adapted  from  subroutines  TAPER  and  MODDAN  given  on  pages 
116  and  178  of  Bloomfield  [1976], 
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CHAPTER  13 


ARIMA  MODELING 


A.  Introduction 

STARPAC  contains  five  user-callable  subroutines  for  AutoRegressive  Tnte- 
grated  Moving  Average  (ARIMA)  modeling.  Three  are  for  computing  the  least 
squares  estimates  of  the  parameters  of  an  ARIMA  model  and  two  are  for 
computing  the  minimum  mean  square  error  forecasts  using  these  estimates.  Both 
the  estimation  and  forecasting  subroutines  allow  several  levels  of  control  of 
the  computations  and  printed  output.  The  estimation  subroutines  also  allow 
the  user  to  specify  a subset  of  the  parameters  to  be  treated  as  constants  with 
their  values  held  fixed  at  their  input  values.  This  last  feature  allows  the 
user  to  examine  the  results  obtained  estimating  various  subsets  of  the 
parameters  of  a general  model  without  respecifying  the  model  for  each  subset. 


Each  of  the  subroutines  in  this  chapter  models  the  input  series,  y^, 
i = 1,  ...,  N,  with  a user-specified  general  multiplicative  ARIMA  model  using 
the  techniques  discussed  in  Box  and  Jenkins  [1976].  Briefly,  this  model  is 
defined  by 


NFAC 


NFAC 


NFAC 


[ n (44>(j)(Bs(j)))][(  n (vs(j))d(j>)  yi-u]  - [ n (e^^assU)))^ 
j=l  j=l  j=l 


for  i = 1, 


N 

NFAC 

Bs 


y 


. . . , N,  where 

is  the  number  of  observations  in  the  series; 

is  the  number  of  factors  in  the  model; 

is  the  backward  shift  operator  of  order  s,  i.e. , 

bS  v±  = yi-s; 

is  the  expected  value  of  the  differenced  series,  i.e. , 
NFAC 

y = E [ II  ( Vs( j J ))  Yi]  , 

j-1 


which  can  be  used  to  allow  for  a deterministic  polynomial  trend; 
<[>p(j  )(Bs(j ) ) is  the  polynomial  in  BS^J^  of  order  p(j),  i.e., 

Mj)(BS(J)>  * 

1 - - *2>jB2*s<j>  - ...  *p(j),jBP<J),S(J). 

which  represents  the  jth  autoregressive  factor  in  the  model; 


13-1 


(V s ( j ) ) d^^  is  the  backward  difference  operator,  i.e., 

(vs(j))d(j)  = (1  - Bs^))d^) 

= 1 - d(j)Bs^>  + ...  Bd(j)*s(j>, 
which  represents  the  jth  difference  factor  in  the  model; 

0_q(  j )( Bs^j ))  is  the  polynomial  in  Bs^j^  of  order  q(j),  i.e., 

! - 01,jBS(j)  - 02,jB2-s<J)  - ...  8q(j)(jBqO)-8«), 

which  represents  the  j1-*1  moving  average  factor  in  the  model;  and 

a-j_  is  the  unobservable  random  noise  component  at  the  i1-*1 

observation. 

The  least  squares  estimates  of  the  parameters, 

4>1,1»  $2,1*  ***’  <f>p(l),l’  *1,2*  ^p(NFAC)  ,NFAC»  u ’ 

01S1»  0 2, 1 » •••»  0q ( 1 ) , 1 » 9 1 , 2 » •••»  0q (NFAC) ,NFAC 

are  obtained  using  back  forecasts  at  each  iteration  as  discussed  in  §E.l.a. 
The  least  squares  solution  is  that  which  minimizes  (with  respect  to  the 
parameters)  the  sum  of  the  squares  of  the  random  noise  components,  a^ , i.e., 

N - 

I *i2 

i=-oo 

where  carat  (* ) denotes  the  estimated  quantity.  The  iterative  procedure  used 
is  documented  in  chapter  9. 

The  user  must  supply  both  initial  values  for  the  parameters  and  an  array 
specifying  the  orders  p(j)»  d(j),  q(j)  and  s(j)  for  each  factor  j = 1,  ..., 
NFAC  in  the  model.  Initial  parameter  values  for  the  estimation  subroutines 
should  be  chosen  with  care  since  good  values  can  significantly  reduce  computer 
time . 


Users  are  directed  to  §B  for  a brief  description  of  the  subrout 
declaration  and  CALL  statements  are  given  in  §C  and  the  subroutine 
are  defined  in  §D.  The  algorithms  used  and  output  produced 
subroutines  are  discussed  in  §E.  Sample  programs  and  their  output 
in  §F. 


ines.  The 
arguments 
by  these 
are  shown 
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B . Subroutine  Descriptions 


B.l  ARIMA  Estimation  Subroutines 


The  simplest  of  the  three  ARIMA  estimation  subroutines,  AIME, 
automatically  summarizes  the  estimated  results  and  a variety  of  statistics  in 
a five-part  printed  report  described  in  §E.2.a,  and  returns  the  estimated 
parameters  and  residuals  to  the  user  via  the  subroutine  argument  list  (level 
one  control).  Most  ARIMA  estimation  problems  can  be  solved  using  AIME. 

The  other  two  estimation  subroutines,  AIMEC  and  AIMES,  provide  greater 
flexibility  to  the  user  at  the  price  of  more  input. 

AIMEC,  like  AIME,  also  returns  estimated  parameters  and  residuals  from 
the  fit.  In  addition,  it  allows  the  user  to  supply  arguments  to  indicate 

- a subset  of  the  model  parameters  to  be  treated  as  constants, 
with  their  values  held  fixed  at  their  input  values; 

- the  step  sizes  used  to  compute  the  numerical  approximations  to 
the  derivative  as  described  in  chapter  9,  §E.l.b; 

- the  maximum  number  of  iterations  allowed; 

- the  convergence  criteria; 

- the  scale  (i.e.  , the  typical  size)  of  each  parameter; 

- the  maximum  change  allowed  in  the  parameters  at  the  first 
iteration; 

- how  the  variance-covariance  matrix  is  to  be  approximated;  and 

- what  sections  of  the  five-part  printed  report  are  wanted. 

AIMES  has  all  the  features  of  AIMEC  and,  in  addition,  returns  the 
following  estimated  values  via  the  argument  list: 

- the  number  of  parameters  actually  estimated; 

- the  residual  standard  deviation; 

- the  predicted  values; 

- the  standard  deviations  of  the  predicted  values; 

- the  standardized  residuals;  and 

- the  variance-covariance  matrix  of  the  estimated  parameters. 


B ,2  ARIMA  Forecasting  Subroutines 

The  simplest  of  the  three  ARIMA  forecasting  subroutines,  AIMF, 
automatically  summarizes  the  estimated  results  in  a two-part  printed  report. 
Forecasts  are  made  using  N as  the  origin  and  extending  [N/10]  + 1 steps  into 
the  future,  i.e.,  observations  are  forecast  for  indices  N+l, 
N+2,  ...,  N+[N/10]+1.  Many  forecasting  problems  can  be  solved  using  AIMF. 

The  second  forecasting  subroutine,  AIMFS,  allows  the  user  to  supply 
arguments  to  indicate  the  number  of  forecasts  to  be  made,  the  origins  to  be 
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used  and  the  amount  of  printed  output.  This  subroutine  also  returns  the 
forecasts  and  their  standard  deviations  via  the  argument  list. 

C . Subroutine  Declaration  and  CALL  Statements 

NOTE:  Argument  definitions  and  sample  programs  are  given  in  §D  and  §F, 

respectively.  The  conventions  used  to  present  the  following  declaration  and 
CALL  statments  are  given  in  chapter  1,  §B  and  §D. 

The  <basic  declaration  block>  identifies  declaration  statements  that  are 
needed  by  all  of  the  ARIMA  estimation  and  forecasting  subroutines.  The  user 
should  substitute  the  following  four  statements  for  each  occurrence  of  <basic 
declaration  block>  given  below. 

<real>  Y (n),  PAR( npar) 

INTEGER  MSPEC  (4 ,nfaa) 

DOUBLE  PRECISION  DSTAK (Idstak) 

COMMON  / CSTAK/  DSTAK 


Subroutine  for  ARIMA  Estimation 

AIME  i Compute  and  print  a five-part  least  squares  analysis  of  the  parameter 
estimates  of  an  ARIMA  model ; return  parameter  estimates  and  residuals 

<basic  declaration  block> 

<real>  RES(n) 


CALL  AIME  (Y,  N,  MSPEC,  NFAC , PAR,  NPAR,  RES,  LDSTAK) 


AIMEC : Compute  and  optionally  print  a five-part  least  squares  analysis  of 

the  parameter  estimates  of  an  ARIMA  model  using  user- supplied  control 
values ; return  parameter  estimates  and  residuals 

<basic  declaration  block> 

<real>  RES(n) 

INTEGER  IFIXED (npar) 

<real>  STP (npar),  STOPSS,  STOPP,  S C ALE (npar ) f DELTA 


CALL  AIMEC  (Y,  N,  MSPEC,  NFAC,  PAR,  NPAR,  RES,  LDSTAK, 

1 IFIXED,  STP,  MIT,  STOPSS,  STOPP,  SCALE,  DELTA,  IVAPRX , NPRT ) 
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AIMES:  Compute  and  optionally  print  a five-part  least  squares  analysis  of 

the  parameter  estimates  of  an  ARIMA  model  using  user- supplied  control 
values;  return  parameter  estimates , residuals,  number  of  parameters 
estimated,  residual  standard  deviation,  predicted  values,  standard 
deviations  of  the  predicted  values  and  variance- covariance  matrix  of 
the  estimated  parameters 

<basic  declaration  block> 

<real>  RES(rc) 

INTEGER  IFIXED (npar) 

<real>  STP(npar’),  STOPSS,  STOPP,  SCALE  (npar») , DELTA 
<real>  RSD,  PV(rc),  SDPV(n),  SDRES(n),  VC V (npare,npare) 


CALL  AIMES  (Y,  N,  M,  MSPEC,  NFAR,  PAR,  NPAR,  RES,  LDSTAK, 

1 IFIXED,  STP,  MIT,  STOPSS,  STOPP,  SCALE,  DELTA,  IVAPRX,  NPRT, 

2 NPARE , RSD,  PV,  SDPV,  SDRES , VCV , IVCV) 


Subroutines  for  ARIMA  Forecasting 


AIMF:  Compute  and  print  the  minimum  mean  square  error  forecasts  obtained 

using  an  ARIMA  model 

<basic  declaration  block> 


CALL  AIMF  (Y,  N,  MSPEC,  NFAC , PAR,  NPAR,  LDSTAK) 


AIMFS:  Compute  and  optionally  print  the  minimum  mean  square  error  forecasts 

obtained  using  an  ARIMA  model;  return  forecasts  and  their  standard 
errors 

<basic  declaration  block> 

<real>  FCST (nfcst ,nfcsto) , SDFCST (nfcst) 

INTEGER  IFCSTO(nfesto) 


CALL  AIMFS  (Y,  N,  MSPEC,  NFAC,  PAR,  NPAR,  LDSTAK, 

1 NFCST,  NFCSTO,  IFCSTO,  NPRT,  FCST,  IFCST,  FCSTSD) 


D.  Dictionary  of  Subroutine  Arguments  and  COMMON  Variables 


NOTE: 


— > indicates  that  the  argument  is  input  to  the  subroutine  and  that 
the  input  value  is  preserved; 

< — indicates  that  the  argument  is  returned  by  the  subroutine; 

<->  indicates  that  the  argument  is  input  to  the  subroutine  and  that 
the  input  value  is  overwritten  by  the  subroutine; 

indicates  that  the  argument  is  input  to  some  subroutines  and  is 

returned  by  others; 

***  indicates  that  the  argument  is  a subroutine  name; 

•••  indicates  that  the  variable  is  passed  via  COMMON. 
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DELTA 


-->  The  maximum  scaled  change  allowed  in  the  parameters  at  the  first 
iteration,  i.e.  , 6q.  [See  chapter  9,  §E.l.a.]  The  default  value 
is  100.0.  When  DELTA  < 0.0  or  when  DELTA  is  not  an  argument  of 
the  subroutine  CALL  statement  the  default  value  is  used.  Normal- 
ly, the  default  value  should  be  used.  However  a smaller  value  of 
DELTA  may  be  appropriate  if,  at  the  first  iteration,  the  computa- 
tion of  the  predicted  values  produces  an  arithmetric  overflow  or 
the  parameters  leave  the  region  of  interest  in  parameter  space.  A 
reasonable  alternative  to  the  default  value  of  DELTA  is  an  upper 
bound  to  the  scaled  change  that  the  estimated  parameters  should  be 
allowed  to  make  on  the  first  iteration, 

DELTA  = min{ |AmaxPAR(k) | /SCALE(k),  for  k = 1,  ...,  NPAR} 

where  A_ovPAR(k)  is  the  maximum  change  allowed  for  the  k1^ 
parameter  at  the  first  iteration. 

DSTAK  •••  The  DOUBLE  PRECISION  vector  in  COMMON  / CSTAK/  of  dimension  at 
least  LDSTAK.  DSTAK  provides  workspace  for  the  computations.  The 
first  LDSTAK  locations  of  DSTAK  will  be  overwritten  during 
subroutine  execution. 

FCST  <”-  The  array  of  dimension  at  least  NFCST  by  NFCSTO  that  contains  the 
NFCST  forecasts  computed  from  each  of  the  NFCSTO  origins. 

FCSTSD  <—  The  vector  of  dimension  at  least  NFCST  that  contains  the  standard 
deviation  of  each  of  the  forecasts, 


K-l 

FCSTSD(K)  = RSD  * ( J '{'i2)1/2  for  K = 1,  ...,  NFCST, 

‘j-o 

where 

= 1 and  Yj  = + ...  + '['p+D * ^ j -P-D  “ ej 

NFAC  NFAC 

with  P = £ p(j);  D = £ d(j);  and 

j=l  j“l 


ip ^ = the  coefficient  of  B1  in  the  polynomial  defined  by 
NFAC 

1 (■tp(j)(BS(J)))-((Vs(j)dj) 

j=l 
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IERR 


***  An  error  flag  returned  in  COMMON  /ERRCHK/ . [See  chapter  1,  §D.5.] 

Note  that  using  (or  not  using)  the  error  flag  will  not  affect  the 
printed  error  messages  that  are  automatically  provided  even  when 
the  user  has  suppressed  the  normal  printed  output. 

For  AIME,  AIMEC , and  AIMES: 

IERR  = 0 indicates  that  no  errors  were  detected  and  that  the 
iterations  converged  satisfactorily. 

IERR  = 1 indicates  that  improper  input  was  detected. 

IERR  = 2 indicates  that  the  computation  of  the  residual  sum  of 
squares  using  the  initial  parameter  values  produced  an 
arithmetic  overflow.  The  user  should  reduce  the  size 
of  DELTA  or  should  supply  new  starting  values. 

IERR  = 3 indicates  that  the  model  is  computationally  singular, 
which  means  the  model  has  too  many  parameters  near  the 
solution.  The  user  should  examine  the  model  and  data 
to  identify  and  remove  the  cause  of  the  singularity. 

IERR  = 4 indicates  that  at  least  one  of  the  standardized  residu- 
als could  not  be  computed  because  its  standard 
deviation  was  zero.  The  validity  of  the  variance- 
covariance  matrix  is  questionable. 

IERR  = 5 indicates  false  convergence.  [See  chapter  9,  §E.l.a.] 

IERR  = 6 indicates  that  convergence  was  not  reached  in  the 
allowed  number  of  iterations  or  model  subroutine  calls. 
[See  argument  MIT.] 

IERR  = 7 indicates  that  the  variance-covariance  matrix  could  not 
be  computed  because  of  computational  difficulties. 

For  AIMF  and  AIMFS: 

IERR  = 0 indicates  that  no  errors  were  detected  and  that  all  the 
forecasts  were  computed. 

IERR  = 1 indicates  that  improper  input  was  detected. 

IFCST  — > The  exact  value  of  the  first  dimension  of  the  matrix  FSCT  as 

specified  in  the  calling  subroutine. 

IFCSTO  — > The  vector  of  dimension  at  least  NFCSTO  that  contains  the  NFCSTO 
indices  to  be  used  as  origins,  where  l < IFCSTO(J)  < N for  J = 1, 
...,  NFCSTO.  The  default  value  for  each  element  of  IFCSTO  is  N. 
When  IFCSTO(J)  is  outside  the  range  [1,  N]  or  IFCSTO  is  not  an 
argument  of  the  subroutine  CALL  statement  the  default  value  is 
used. 


13-7 


IFIXED  - — > The  vector  of  dimension  at  least  NPAR  that  contains  values  used  to 
indicate  whether  the  corresponding  parameter  in  PAR  is  to  be 
treated  as  a fixed  constant  or  is  to  be  estimated.  If 
IFIXED(I)>0,  PAR(I)  will  be  held  fixed  at  its  input  value;  if 
IFIXED( I )=0 , PAR ( I ) will  be  estimated  using  the  least  squares 
procedure  described  in  §A.  The  default  values  are  IFIXED(I)=0,  I 
= 1,  . ..,  NPAR,  i.e. , all  parameters  are  estimated.  When 

IFIXED(1)<-1  or  when  IFIXED  is  not  an  argument  of  the  subroutine 
CALL  statement  the  default  value  will  be  used. 

IVCV  ““>  The  exact  value  of  the  first  dimension  of  the  matrix  VCV  as 
specified  in  the  calling  program. 

IVAPRX  --->  The  indicator  variable  used  to  specify  how  the  variance-covariance 
matrix,  VCV,  is  to  be  approximated.  Three  approximations  are 
available: 

a <*» 

(1)  VCV  = RSD2® (DT«D)“1 

(2)  VCV  = RSD2 • H”1 

(3)  VCV  ---  RSD2  « H”1 « (DT«  D)  •H~l 
where 

Dtj  = aa-jyas  (j  ) for  i 

and  j 

<A.  A N <*»  /</=>.  A 

H = DT®  D - { l a1*(32ai/3e(j)36(k>)  for  j 

i=l  and  k 

The  results  of  a recent  study  by  Donaldso 
indicate  that  approximation  (1)  is  prefe 
simple,  less  expensive,  more  numerically  s 
accurate  as  approximations  (2)  and 
approximations  to  the  variance-covariance  matrix  are  subject  to 
sampling  variation  because  they  are  computed  using  the  estimated 
parameter  values.  The  variance-covariance  matrix  computed  for  any 
particular  nonlinear  least  squares  solution  should  thus  be 
regarded  as  only  a rough  estimate  [Bard,  1974;  Donaldson  and 
Schnabel,  1985]  . 

If  IVAPRX  - lor  4 then  approximation  (1)  is  used; 

= 2 or  5 then  approximation  (2)  is  used;  and 

= 3 or  6 then  approximation  (3)  is  used. 

The  default  value  for  IVAPRX  is  1.  When  argument  IVAPRX  is 

outside  the  range  [1,  6]  or  when  IVAPRX  is  not  an  argument  of  the 
subroutine  CALL  statement  then  the  default  value  is  used. 


= 1, 
= 1, 


, N 

, NPAR;  and 


= 1 , . . . , NPAR 
= 1 , . . . , NPAR}  . 

n and  Schnabel  [1985] 
rable  because  it  is 
table  and  at  least  as 
(3).  However,  all 
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LDSTAK 


— > The  length  of  the  DOUBLE  PRECISION  workspace  vector  DSTAK.  LDSTAK 
must  equal  or  exceed  the  appropriate  value  given  below,  where  if 
the  single  precision  version  of  STARPAC  is  being  used  P = 0.5, 
otherwise  P = 1.0.  [See  chapter  1,  §B.]  Also, 

NFAC  NFAC 

MBO  = maximum  { [ (p( j )+d( j )) »s( j ) , £ qCj)-s(j)  }. 

j=l  j-1 


For  AIME,  AIMEC  and  AIMES: 

LDSTAK  ^ 43  + max{ IS* (N+NPAR) , 30+NPARE}  + 2»  NFAC  + 
max  { IS«10»N  + 6*MB0+606. 

94  + 4 • ( N+MB0+ 101)  + 5»MBO  + ( 3 « NPARE2  +3  5«  NPARE  ) / 2 }*P 

where  IS  = 1 if  default  values  are  used  for  the  derivative 
step  sizes,  and  IS  = 0 otherwise. 


For  AIMF  and  AIMFS : 

LDSTAK  > 18  + 2»  NFAC  + ( 5*MBO+2« (N+MBO+101)) • P 

MIT  — ->  The  maximum  number  of  iterations  allowed.  This  argument  is  also 

used  to  compute  the  maximum  number  of  model  subroutine  calls, 
(2*MIT).  The  iterations  will  stop  if  either  limit  is  reached, 
although,  as  a rule,  the  maximum  number  of  iterations  will  be 
reached  first.  The  default  value  for  the  maximum  number  of 
iterations  is  21.  When  MIT  < 0 or  when  MIT  is  not  an  argument  of 
the  subroutine  CALL  statement  the  default  value  is  used. 


MSPEC 


— > The  array  of  dimension  exactly  4 rows 
that  contains  the  orders  p,  d,  q and 
model  where  p(j),  j = 1,  ...,  NFAC  must 

d ( j ) , j = 1,  ...,  NFAC  must 

q(j),  j = 1>  •••»  NFAC  must 

s(j),  j = 1,  ...,  NFAC  must 

Values  of  p(j),  d(j),  q(j)  and  s(j),  j 
equal  or  exceed  zero. 


by  at  least  NFAC  columns 
s for  each  factor  in  the 
be  in  row  1, 
be  in  row  2, 
be  in  row  3,  and 
be  in  row  4. 

= 1,  ...,  NFAC,  must  each 


N 


— > The  number  of  observations. 


NFAC  — > The  number  of  factors  in  the  model. 


NFCST  — > The  number  of  forecasts  to  be  computed.  The  default  value  is 
[N/10]+l.  When  NFCST<0  or  when  NFCST  is  not  an  argument  of  the 

subroutine  CALL  statement  the  default  value  is  used. 

NFCSTO  — > The  number  of  forecast  origins  supplied.  The  default  value  is  1. 

When  NFCSTO<0  or  when  NFCSTO  is  not  an  argument  of  the  subroutine 
CALL  statement  the  default  value  is  used. 
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NPAR 


— > The  number  of  parameters  in  the  model  including  both  those  held 
fixed  at  their  starting  values  and  those  which  are  to  be 
estimated, 


NFAC 

NPAR  = 1 + l (p(j)  + q(j))  . 

j-1 

NPARE  <—  The  number  of  parameters  actually  estimated,  i.e.  , the  number  of 
zero  elements  in  IFIXED.  N.B.  This  value  is  returned  by  the 
estimation  subroutines. 

NPRT  —>  The  argument  controlling  printed  output. 

For  AIME,  AIMEC  and  AIMES: 

NPRT  is  a five-digit  integer  for  which  the  value  of  the  Ith 
digit  (counting  from  left  to  right)  is  used  to  control  the  Ith 
section  of  the  output. 

If  the  I1-*1  digit  = 0 the  output  from  the  I1-*1  section  is 

suppressed ; 

= 1 the  brief  form  of  the  I^  section  is  given; 

> 2 the  full  form  of  the  Ic^  section  is  given. 

The  default  value  for  NPRT  is  11112.  When  NPRT  < -1  or  when 
NPRT  is  not  an  argument  in  the  subroutine  CALL  statement  the 
default  value  is  used.  If  the  convergence  criteria  are  not 
satisfied,  the  subroutine  gives  a suitable  warning  and  provides 
a printed  report  even  if  NPRT  =0.  A full  discussion  of  the 
printed  output  is  given  in  §E.2.a  and  is  summarized  as  follows. 

Section  1 lists  the  starting  estimates  and  control  values. 

Brief  output  and  full  output  are  the  same  for  this 
section. 

Section  2 reports  the  results  of  the  iterations.  Brief  output 
includes  information  only  about  the  first  and  last 
iteration  while  full  output  includes  information  about 
all  of  the  iterations. 

Section  3 provides  information  for  each  observation  based  on  the 
final  solution.  Brief  output  includes  information  for 
the  first  40  observations  while  full  output  provides 
the  information  for  all  of  the  data. 

Section  4 is  a set  of  four  residual  plots.  Brief  output  and 
full  output  are  the  same  for  this  section. 

Section  5 is  the  final  summary  of  the  estimated  parameters. 

Brief  output  does  not  include  printing  the  variance- 
covariance  matrix  while  full  output  does. 

— continued  — 
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For  AIMF  and  AIMFS: 


If  NPRT  = 0 the  printed  output  is  suppressed. 

If  NPRT  * 0 the  printed  output  is  provided. 

The  default  value  for  NPRT  is  1.  When  NPRT<-1  or  when  NPRT  is 

not  an  argument  in  the  subroutine  CALL  statement  the  default 
value  will  be  used. 

PAR  The  vector  of  dimension  at  least  NPAR  that  contains  the  parameter 

values.  For  both  the  estimation  and  the  forecasting  subroutines, 
parameter  values  must  be  ordered 

*1,1*  ^2,1*  •••»  *p(l),l.  ^1,2’  ' * 0 ’ ^p(NFAC) ,NFACS 
M > 

01,1»  8 2, 1 » 8 q( 1 ) , 1 ’ 8 1 , 2>  •••»  0q(NFAC),NFAC» 

i.e.,  the  parameter  values  from  the  autoregressive  factors  are 
first,  followed  by  p,  followed  by  the  parameter  values  from  the 
moving  average  factors.  For  all  estimation  subroutines  PAR  must 
contain  initial  values  for  the  parameters  on  input  and  will 
contain  the  final  values  on  return.  For  the  forecasting  subrou- 
tines PAR  must  contain  the  parameter  values  for  which  the 
forecasts  are  to  be  computed. 

PV  < — • The  vector  of  dimension  at  least  N that  contains  the  predicted 

values  of  the  dependent  variable  at  the  solution, 

A 

PV(i)  = yi  “ ai  for  i = 1,  . . , N. 

RES  <--  The  vector  of  dimension  at  least  N that  contains  the  residuals  at 
the  solution, 

A 

RES(i)  = a(i)  for  i = 1,  ...,  N„ 

RSD  < — The  residual  standard  deviation  at  the  solution, 

N 1/2 

RSD  = [(  l RES(i)2)/(N-NPARDF-NPARE)] 
i=l 

NFAC 

where  NPARDF  = £ s(j)*d(j)  . 

j-1 
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SCALE 


-->  The  vector  of  dimension  at  least  NPAR  that  contains  the  scale,  or 
typical  size,  of  each  parameter.  The  vector  SCALE  is  used  to 
normalize  the  size  of  each  parameter  so  that 

| PAR^  ( j ) / SCALE( j ) | » |PAR.£  (k) /SCALE  (k)  | for  j = 1 , ...,  NPAR 

and  k = 1 , . . . , NPAR, 

where  PAR^ ( j ) is  the  value  of  the  jth  parameter  at  the  £th 

iteration.  Values  of  |SCALE(k)|  > |PAR^(k)|  can  be  used  to 

increase  the  step  size  in  cases  where  the  model  function  is  known 

to  be  insensitive  to  small  changes  in  the  value  PAR^(k),  although 
normally  the  default  values  should  be  used. 

The  default  values  for  SCALE  are  selected  by  the  NL2S0L  algorithm 
[Dennis  et  al®  1981a  and  1981b]  and  are  updated  at  each 

iteration.  When  SCALE  is  not  an  argument  in  the  subroutine  CALL 
statement  or  when  the  user-supplied  value  for  SCALE(1)<0  the 
default  procedure  will  be  used  to  select  scale  values.  When 
SCALE(1)>0,  values  of  SCALE(k)<0  for  k = 2,  ...,  NPAR  will  be 

interpreted  as  an  input  error.  User-supplied  scale  values  may  be 
either  a vector  of  the  typical  size  of  each  parameter  or  a vector 
of  ones  if  the  typical  sizes  of  the  parameters  are  roughly  equal; 
user-supplied  scale  values  can  sometimes  result  in  reduced  com- 
puting time  since  these  values  are  not  updated  at  each  iteration. 

SDPV  <—  The  vector  of  dimension  at  least  N that  contains  an  approximation 
to  the  standard  deviation  of  each  predicted  value  at  the 
solution, 

A A 

SDPV(i)  = the  it^1  diagonal  element  of  [ (D»  VCV»  D^)] 
for  i - 1,  N,  where 

Djj  = 9 a^/88  (j ) for  i = 1,  . ..,  N and  j = 1,  ...,  NPAR. 

This  approximation  is  based  on  a linearization  of  the  model  in  the 
neighborhood  of  the  solution;  the  validity  of  the  approximation 
depends  on  the  nonlinearity  of  the  model.  This  approximation  may 
be  extremely  inaccurate  for  a problem  with  a highly  nonlinear 

model. 

SDRES  <—  The  vector  of  dimension  at  least  N that  contains  an  approximation 
to  the  standardized  residuals  at  the  solution, 

SDRES (i  ) - RES(i)  / [ RSD2-SDPV(i  )2 ] 1 72 

for  i = 1,  . N,  which  is  the  i11*1  residual  divided  by  its 

individual  estimated  standard  deviation.  This  approximation  is 
based  on  a linearization  of  the  model  in  the  neighborhood  of  the 
solution;  the  validity  of  the  approximation  depends  on  the 

nonlinearity  of  the  model.  This  approximation  may  be  extremely 

inaccurate  for  a problem  with  a highly  nonlinear  model. 
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STOPP  -->  The  stopping  value  for  the  convergence  test  based  on  the  maximum 
scaled  relative  change  in  the  parameters  at  the  most  recent 
iteration.  The  convergence  criterion  is  satisfied  if  the  current 
step  is  a Newton  step  and 


max{ 

|PAR„+i  (k)-PAR„  (k)  | 

| /SCALE  (k)  for  k = 1,  ...,  NPAR} 

max{  | 

n 

PARj£  + 1(k)  | + 

PAR^ (k) | J / SCALE (k)  for  k = 1,  ...,  NPAR} 

< STOPP 


where  PAR^(k)  is  the  value  of  the  k*-*1  parameter  at  the  2^ 
iteration.  [See  Dennis  et  al.  1981a. ] This  convergence  test  is 
roughly  equivalent  to  the  test  based  on  the  maximum  relative 
change  in  each  parameter  as  measured  by 


max{  |PAR£+1(k)-PAR£(k)|/|PAR^(k)|  for  k = 1,  ...,  NPAR}  . 


STOPP  is  not  a scale-dependent  value;  if  its  value  is  10“**  , then 
this  criteria  will  be  met  when  the  first  four  digits  of  each 
parameter  are  the  same  at  two  successive  iterations  regardless  of 
the  size  of  the  parameter  values. 

The  default  value  is  approximately  io~DIGITS/2^  where  DIGITS  is 
the  number  of  decimal  digits  carried  by  the  user's  computer  for  a 
single  precision  value  when  the  single  precision  version  of 
STARPAC  is  being  used  and  is  the  number  carried  for  a double 
precision  value  otherwise.  When  the  user-supplied  value  for  STOPP 
is  outside  the  interval  [0.0,  1.0]  or  when  STOPP  is  not  an 
argument  of  the  subroutine  CALL  statement  the  default  value  is 
used. 


STOPSS  -->  The  stopping  value  for  the  convergence  test  based  on  the  ratio  of 
the  forecasted  change  in  the  residual  sum  of  squares  at  iteration 
2+1,  ARSS^+i,  to  the  residual  sum  of  squares  at  iteration  2 , 

N - 

RSS^  = £ . 

i=-oo 


The  convergence  criterion  is  satisfied  if  certain  conditions  are 
met  and 

ARSS£+1/RSS£  < STOPSS. 

[See  Dennis  et  al.  1981a.]  This  convergence  test  is  roughly 
equivalent  to  the  test  based  on  the  relative  change  in  the 
residual  standard  deviation  between  two  iterations  2 and  2+1  as 
measured  by  (RSS£1/2  - RSS^+j1  /2  VRSS^1  /2  . STOPSS  is  not  a scale- 
dependent  value;  if  its  value  is  10-^  this  criteria  will  be  met 
when  the  first  five  digits  of  the  residual  sum  of  squares  are  the 
same  at  two  successive  iterations  regardless  of  the  size  of  the 
residual  sum  of  squares. 

— continued  — 


13-13 


STP 


VCV 


The  default  value  is  approximately  the  maximum  of  10  ^ and 
10~2.DIGITS/3>  where  DIGITS  is  the  number  of  decimal  digits 
carried  by  the  user’s  computer  for  a single  precision  value  when 
the  single  precision  version  of  STARPAC  is  being  used  and  is  the 
number  carried  for  a double  precision  value  otherwise.  When  the 
user-supplied  value  for  STOPSS  is  outside  the  interval 
[10  0.1]  or  when  STOPSS  is  not  an  argument  of  the 
subroutine  CALL  statement  the  default  value  will  be  used. 


— The  vector  of  dimension  at  least  NPAR  that  contains  the  relative 
step  sizes  used  by  the  estimation  subroutines  to  approximate  the 
derivative  matrix  numerically.  The  procedure  used  to  select  the 
default  values  is  described  in  chapter  9,  §E.l.a.  When  STP  is  not 
an  argument  of  the  subroutine  CALL  statement  or  when  STP(1)<0  the 
default  values  will  be  used  for  all  of  the  step  sizes;  when 
STP( 1 )>0  s values  of  STP(k)<0  for  k = 2,  ...,  NPAR  will  be 

interpreted  as  an  input  error. 


<--  The  matrix  of  dimension  at  least  NPARE  by  NPARE  that  contains  the 
variance-covariance  matrix  of  the  estimated  parameters,  approxi- 
mated as  designated  by  argument  IVAPRX.  The  parameters  which  are 
held  fixed  (as  specified  by  argument  IFIXED)  are  not  included  in 
the  variance-covariance  matrix. 


The  approximation  of  the  variance-covariance  matrix  is  based  on  a 
linearization  of  the  model  in  the  neighborhood  of  the  solution; 
the  validity  of  the  approximation  depends  on  the  nonlinearity  of 
the  model.  This  approximation  may  be  extremely  inaccurate  for  a 
problem  with  a highly  nonlinear  model. 

Y — > The  vector  of  dimension  at  least  N that  contains  the  series  being 
modeled. 


E o Computational  Methods 

E . 1 Algorithms 

E.l.a  ARIMA  Estimation 


The  ARIMA  estimation  subroutines  use  the  NL2S0L  software  package  written 
by  Dennis  et  al.  [1981a  and  1981b].  The  observations  of  the  series,  which  are 
measured  with  error,  are  iteratively  fit  to  the  ARIMA  model  by  minimizing  the 
sums  of  squares  of  the  estimated  random  noise  component  as  described  in  §A. 
The  back  forecasting  technique  discussed  on  pages  215-220  of  Box  and  Jenkins 
[1976]  is  used  to  compute  the  random  noise  component.  Up  to  101  back 
forecasts  are  computed.  The  back  forecasts  are  assumed  to  be  negligible  when 
their  magnitude  is  less  than  0.01  times  the  first  value  of  the  differenced 
series  (centered  about  its  mean)  obtained  entirely  from  the  observed  data. 
If,  at  the  last  iteration,  the  101st  back  forecast  is  not  negligible  a warning 
message  is  printed. 
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The  iterations  continue  until  the  convergence  criteria  based  on  the 
change  in  the  parameter  values  or  in  the  residual  sum  of  squares  are  satisfied 
[arguments  STOPP  and  STOPSS],  the  maximum  number  of  iterations  (or  model 
subroutine  calls)  is  reached  [argument  MIT],  or  the  iterations  are  terminated 
due  to  singularity  in  the  model  or  false  convergence.  All  but  the  first  of 
these  stopping  conditions  may  indicate  computational  problems  and  will  produce 
an  error  report.  [See  chapter  1,  §D . 5 . ] Singular  convergence  means  that  the 
model  contains  too  many  parameters,  at  least  near  the  solution,  while  false 
convergence  can  indicate  that  either  STOPSS  or  STOPP  is  set  too  small  for  the 
accuracy  to  which  the  model  and  its  derivatives  are  being  computed  or  that 
there  is  a discontinuity  in  the  derivative.  Iterative  procedures  for  solving 
nonlinear  least  squares  problems  are  discussed  in  Dennis  and  Schnabel  [1983], 
Draper  and  Smith  [1981] , and  Kennedy  and  Gentle  [1980] . The  specific 
procedure  used  in  STARPAC  is  discussed  in  chapter  9 and  Dennis  et  al. 
[1981a] . 


E.l.b  ARIMA  Forecasting 

The  ARIMA  forecasting  subroutines  use  the  techniques  discussed  in  Box  and 
Jenkins  [1976],  chapter  5.  The  back  forecasting  technique  discussed  on  pages 
215-220  of  Box  and  Jenkins  [1976]  is  used  to  compute  the  random  noise 
component  needed  for  the  forecasts.  Values  of  a ^ for  i greater  than  the 
forecast  origin  are  assumed  to  be  zero.  Up  to  101  back  forecasts  are 
computed.  The  back  forecasts  are  assumed  to  be  negligible  when  their 
magnitude  is  less  than  0.01  times  the  first  value  of  the  differenced  series 
(centered  about  its  mean)  obtained  entirely  from  the  observed  data.  If  the 
101st  back  forecast  is  not  negligible  a warning  message  is  printed. 


E . 2 Computed  Results  and  Printed  Output 

E„2.a  The  ARIMA  Estimation  Subroutines 

The  argument  controlling  the  printed  output,  NPRT,  is  discussed  in  §D. 

The  output  from  the  ARIMA  estimation  subroutines  consists  of  five 
sections,  several  of  which  include  tables  summarizing  the  results.  In  the 
following  descriptions,  the  actual  table  headings  are  given  by  the  underlined, 
uppercase  phrases.  Results  which  correspond  to  input  or  returned  subroutine 
CALL  statement  arguments  are  identified  by  the  argument  name  in  uppercase 
(not  underlined). 

Section  1 provides  a summary  of  the  initial  estimates  and  control  values.  It 
lists  the  following  information. 

© The  initial  values  of  the  parameters,  PAR,  and  whether  they  are  to  be 
held  fixed  or  not  as  indicated  by  argument  IFIXED. 

• The  scale  values,  SCALE. 
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• The  step  sizes  used  to  approximate  the  derivatives  numerically,  STP. 

• The  number  of  observations,  N. 

• The  maximum  number  of  iterations  allowed,  MIT. 

• The  maximum  number  of  model  subroutine  calls  allowed. 

• The  two  convergence  criteria,  STOPSS  and  STOPP. 

• The  maximum  change  in  the  parameters  allowed  at  the  first  iteration, 
DELTA. 

• The  residual  sum  of  squares  computed  using  the  starting  parameter 
values. 

• The  residual  standard  deviation  computed  using  the  starting  parameter 
values,  RSD. 

Section  2 lists  selected  information  about  each  iteration  and  includes  the 
reason  the  iterations  were  terminated.  The  information  provided  for 
each  iteration  includes  the  following. 

• The  iteration  number. 

• MODEL  CALLS;  the  total  number  of  times  since  execution  began  that  the 
user's  model  subroutine  has  been  called,  not  including  calls  required 
to  approximate  the  derivatives  numerically. 

• RSD i the  residual  standard  deviation  computed  using  the  parameter 

values  from  the  current  iteration. 

• RSS s the  residual  sum  of  squares  computed  using  the  parameter  values 
from  the  current  iteration. 

® REL  CHNG  RSS;  the  relative  change  in  the  residual  sum  of  squares 
resulting  from  the  current  iteration. 

• FORECASTED  REL  CHNG  RSS : the  forecasted  relative  change  in  the  resid- 

ual sum  of  squares  at  the  current  iteration  and  whether  this  value  was 
checked  against  STOPSS  (CHKD  = Y)  or  not  (CHKD  = N). 

• REL  CHNG  PAR:  the  maximum  scaled  relative  change  in  the  parameters  at 

the  current  iteration  and  whether  this  value  was  checked  against  STOPP 
(CHKD  = Y)  or  not  (CHKD  = N). 

• CURRENT  PARAMETER  VALUES : the  estimated  parameter  values  resulting 

from  the  current  iteration. 
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Section  3 provides  the  following  information  for  each  observation,  i = 1, 

N,  based  on  the  final  solution. 

• ROW : the  row  number  of  the  observations. 

© SERIES : the  value  of  the  dependent  variable,  Y. 

• PREDICTED  VALUE:  the  estimated  predicted  value,  PV,  from  the  fit. 

© STD  DEV  OF  PREP  VALUE:  the  standard  deviation  of  the  predicted 

value,  SDPV. 

© RESIDUAL : the  error  estimate,  RES. 

• STD  RES;  the  standardized  residual,  SDRES. 

Section  4 displays  the  following  plots. 

© The  standardized  residuals  versus  row  numbers. 

• The  autocorrelation  function  of  the  (non-standardized)  residuals. 

• The  normal  probability  plot  of  the  standardized  residuals. 

Section  5 summarizes  the  following  information  about  the  final  parameter 
estimates  and  their  variances. 

• The  variance-covariance  matrix,  VCV,  of  the  estimated  (unfixed) 
parameters  and  the  corresponding  correlation  matrix, 

r jk  = VCV(j,k)/(VCV(j,j)  VCV(k,k))1/2  for  j = 1,  ...,  NPARE 

and  k = 1,  ...,  NPARE. 

• PARAMETER  ESTIMATES  (PAR):  the  final  value  of  each  parameter,  PAR(k), 

k = 1 , . . . , NPAR. 

© STD  DEV  OF  PARAMETER  ESTIMATES:  the  standard  deviation  of  each 

estimated  parameter, 

( VCV(k,k))1/2  for  k = 1,  ...,  NPAR. 

• RATIO  PAR/SD  OF  PAR:  the  ratio  of  each  estimated  parameter  to  its 

standard  deviation, 

RATI Ok  = PAR(k)/(VCV(k,k))1/2  f or  k = 1 , ...,  NPAR. 

• APPROXIMATE  95-PERCENT  CONFIDENCE  LIMITS:  the  lower  and  upper 

95-percent  confidence  limits  for  each  parameter,  computed  using  the 
appropriate  value  of  the  Student's  t distribution  with 
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NFAC 

N - ( l s(j )*d(j ))  - NPARE 

i=l 

degrees  of  freedom. 

• The  residual  sum  of  squares  at  the  solution. 

• The  residual  standard  deviation  at  the  solution,  RSD. 

NFAC 

® The  residual  degrees  of  freedom,  N - ( £ s(j)*d(j))  - NPARE. 

i=l 

• An  approximation  to  the  condition  number  of  the  derivative  matrix, 

Djj  = 3ai/8g(j)  for  i = 1,  ...,  N and  j = 1,  ...,  NPAR 

(the  Jacobian),  under  the  assumption  that  the  absolute  error  in  each 
column  of  D is  roughly  equal.  The  approximation  will  be  meaningless 

if  this  assumption  is  not  valid;  otherwise  it  will  usually 

underestimate  the  actual  condition  number  by  a factor  of  from  2 to  10 
[see  Dongarra  et  al.  1979,  page  9.5], 

NOTE;  The  standard  deviation  of  the  predicted  values,  the  standardized 
residuals,  the  variance-covariance  matrix,  the  standard  deviations  of  the 
parameters  and  the  95-percent  confidence  limits  on  the  parameters  are  all 
based  on  a linear  approximation  to  the  model  in  a neighborhood  of  the 
solution;  the  validity  of  this  approximation  depends  on  the  nonlinearity  of 
the  model.  The  statistics  based  on  this  approximation  may  be  extremely 
inaccurate  for  a problem  with  a highly  nonlinear  model. 


E„2.b  The  ARIMA  Forecasting  Subroutines 


The  argument  controlling  the  printed  output,  NPRT,  is  discussed  in  §D. 

The  output  from  the  ARIMA  forecasting  subroutines  consists  of  a summary 
of  the  model  used  to  produce  the  forecasts  and,  for  each  origin,  a plot  and  a 
list  of  the  computed  forecasts  and  a 95-percent  confidence  interval  about  the 
forecasts  along  with  the  actual  series  value  when  known. 


The  sample 
table  9.1  of  Box 

programs  of  this 
and  Jenkins  [1976] 

section  use  the 
; the  model  is 

model 

and 

data 

given  in 

V1X*V  121®  y± 

- v = (i-e1>rBi) 

° (1—01,2*®^)  * 

a-L  for 

i = 

1,  ... 

, N. 
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ARIMA  Estimation.  In  the  sample  program  of  figure  F-la,  AIME  is  used  to 
compute  the  least  squares  estimates  of  the  parameters;  figures  F-lb  through 
F-lf  show  the  output  from  AIME. 


ARIMA  Forecasting.  In  the  sample  program  of  figures  F-2a,  AIMF  is  used 
to  compute  the  minimum  mean  square  error  forecasts  using  the  least  squares 
estimates  obtained  in  example  1;  figures  F-2b  and  F-2c  show  the  output  from 
AIMF. 
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ARIMA  Estimation 


IAIN  PROGRAM* 

c 

c 

c 

c 

e 

c 

c 

c 

c 

c 


c 

c 

c 

c 

e 

c 

c 

c 

c 

e 

c 


PROGRAM  EXANPL 

DEMONSTRATE  AI«E  OSINS  SINGLE  PRECISION  VERSION  QF  STARPAC 
PUN  ON  CYBER  180/8*0. 

OUTPUT  UNIT  IS  % ( AUTOMATIC  ALLY  EQUATED  TO  PILE  T*9E6  ON  CY8EPS) 

ISEE  CHAPTER  1,  SECTION  D.*3 

N.B.  DECLARATION  OP  Y»  **,  PAR  AND  RES  NUST  9E  CHANGED  TO  OOUBLE  PRECISION 
IP  DOUBLE  PRECISION  VERSION  OF  STARPAC  IS  USED. 

INTEGER  “$  PEC ( *»  5 ) 

REAL  Y ( 200 ) f P AR  t 5 J # 8ES«200> 

DOUBLE  PRECISION  0STAM5006I 

CONNQN  /CSTAN/  ostak 

DEFINE  VARIABLES  FOR  VARIOUS  OINENSIONS 
LDSTAK  • 5006 

READ  NU“BER  OP  FACTORS  IN  MODEL 

VALUES  OP  »»  0,  a AND  S p nR  EACH  factor 

NU»BER  OP  PARANETERS 

STARTIN6  VALUES  FOR  PARANETERS 

NUNBE®  OP  observations 
OBSERVED  SERIES 


READ  100*  N F AC 

READ  100*  UHSPEC(X.J)*  I»1**J»  J«lfNPAC) 
READ  100*  near 

READ  101*  (PAR(I),  I«1*NPAR» 

READ  10 0*  N 

READ  101,  (YCH*  I-l.NJ 

c 

C COMPUTE  LOG  OP  OATA 

C 

DO  10  I ■ 1.  N 

Y( I ) « AL06 ( Y( I ) ) 

10  CONTINUE 


c PRINT  TITLE  and  CALL  A I*  E TO  PERFORM  ARINA  ESTIMATION  ANALYSIS 

C 

VR XTE  <6*  192) 

CALL  A I N | (Y,  N»  N$P|C»  NF  AC » 9 AR  » NPAR,  RES*  LDSTAK) 

C 

STOP 

c 

c FORMAT  STATEMENTS 

c 

loe  format  i*is) 

101  FORMAT  { 12F6 . 1 ) 

10 1 POR«AT  (UBESUITS  OP  STARPAC  ARINA  E ST  !■  AT  ION  SUBROUTINE  A INE  ' ) 

C 

END 

DATA*  2 

0 111 
0 1 1 12 
3 

9.0  0.*  0.6 

U* 


112.0 

118.0 

132.0 

129.0 

121.0 

135.0 

1*8.0 

1*8.0 

136.0 

119.0 

10*. C 

118.9 

115.0 

13  6.0 

1*1.0 

135.0 

125.0 

1*9.0 

170.0 

170.0 

138.0 

133.0 

11*. 0 

1*0.0 

1*5.0 

150.0 

1TB. 0 

163. C 

172.0 

178.0 

199,0 

199.0 

18*.  0 

162.0 

1*6.0 

166.0 

171.0 

1 80.0 

193.0 

181.0 

133.0 

218.0 

230.0 

2*2.0 

299.0 

191.0 

172.0 

19*. 0 

196.0 

196.0 

236.0 

235.0 

229.0 

2*3.0 

26*. 0 

272.0 

237.9 

211  .0 

180.0 

201  .0 

20*. 0 

198.0 

235.0 

227.0 

23*. 0 

26*  .0 

302.0 

293  .0 

259.0 

229.0 

203.0 

229.9 

2*2 .0 

233.0 

267.0 

269.9 

270.0 

315.0 

36*. 0 

3*7.0 

312.0 

27*. 0 

237.0 

278.0 

28*. 0 

277.0 

117. S 

33  3.0 

319.0 

37*. 0 

*13.0 

*05.0 

355.0 

306.0 

271.0 

306.0 

915.0 

101.0 

156.0 

3*8.0 

359.0 

*22.0 

*65.0 

*67.6 

*04.0 

3*7.0 

305.0 

336.0 

3*0.0 

318.0 

1*2.0 

3*8.0 

363  .0 

*35.0 

*91.0 

505.0 

*0*  .0 

359.0 

310.0 

337.0 

360.0 

3*2.0 

*06.0 

396.0 

*20.0 

*72.0 

5*8.0 

559.0 

*63.0 

*97.9 

367.0 

♦ 05.0 

*17.0 

391.0 

*19.0 

*61.0 

*72.0 
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Example  of  AIME  output 
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F.xanple  of  AlME  output  (continued) 
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pjxample  of  AfMR  output  (continued) 
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Example  of  AIME  output  (continued) 
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Example  of  AIMF  output 
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Kx ample  of  AIHF  output  (continued) 
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Appendix  A 


CONTINUITY  OF  VERTICAL  PLOTS 
ON  THE  CDC  CYBER  840  AND  855 


Normally,  a line  printer  will  automatically  provide  margins  at  the  top 
and  bottom  of  each  page  causing  a break  in  the  continuity  of  a vertical  plot 
extending  over  two  or  more  pages.  However,  these  automatic  page-ejects 
within  a vertical  plot  can  be  suppressed  by  the  user  on  many  systems.  On  the 
CDC  Cyber  840  and  855  model  machines  this  would  be  done  by  printing  a Q 
carriage  control  in  column  one  immediately  before  the  call  to  the  vertical 
plot  routine.  Printing  an  R carriage  control  will  cancel  this  effect.  For 
example,  the  sequence 

WRITE  (6,  100) 

100  FORMAT  (1H1 , 23HTITLE  FOR  VERTICAL  PLOT) 

WRITE  (6,  101) 

101  FORMAT  (1HQ) 

CALL  VP  (Y,  N) 

WRITE  (6,  102) 

102  FORMAT  (1HR) 

will  produce  a vertical  plot  beginning  on  a new  page,  without  any  breaks  in 
continuity  and  without  affecting  the  automatic  page-ejects  in  the  rest  of  the 
output.  Users  of  other  systems  should  consult  their  Computer  Center  staff  for 
any  equivalent  method  available. 
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Appendix  B 


WEIGHTED  LEAST  SQUARES 


Weighted  least  squares  can  be  used  to  eliminate  observations  from  the 
analysis  and  to  compensate  for  unequal  variances  in  the  observational  errors. 

Observations  can  be  eliminated  from  the  analysis  by  using  weight  values 
consisting  only  of  zeros  and  ones.  This  will  produce  the  same  results  as 
performing  an  unweighted  analysis  with  the  zero-weighted  values  removed  except 
that  the  predicted  values,  the  standard  deviations  of  the  predicted  values, 
and  the  residuals  of  the  zero-weighted  data  are  computed.  There  are  two  main 
reasons  for  weighting  observations  zero.  The  first  is  to  obtain  the  predicted 
values  and  their  standard  deviations  for  a set  of  independent  variables  not 
included  in  the  observed  data.  (This  is  done  by  assigning  any  arbitrary  value 
to  the  dependent  variable  of  the  desired  set  of  independent  variables,  and 
then  weighting  these  values  zero. ) The  second  reason  is  to  allow  easy 
examination  of  the  effect  of  outliers  and  influential  data  points.  Outliers 
often  appear  as  large  values  in  residual  plots.  Careful  checking  of  the  data 
often  leads  to  confirmation  that  the  data  are  in  error,  and  sometimes  to  a 
correction.  When  a cause  for  suspicious  data  cannot  be  found,  it  may  be 
advisable  to  compare  the  analysis  with  and  without  the  questionable  data. 
Caution  is  in  order  if  the  estimates  or  conclusions  are  highly  sensitive  to  a 
small  amount  of  suspicious  data.  Data  that  have  a very  high  influence  on  a 
fitted  curve  may  not  result  in  large  residuals,  however,  even  if  they  are  in 
error.  In  fact,  extremely  influential  observations  may  force  the  fitted  curve 
to  be  very  close,  leading  to  very  small  residuals.  It  is  therefore  desirable 
to  identify  influential  observations  and  to  compare  the  results  obtained  with 
and  without  these  points.  Several  methods  for  detecting  influential 
observations  are  discussed  in  Bement  and  Williams  [1969] , Cook  [1977] , Hoaglin 
and  Welsch  [1978],  and  Belsley  et  al.  [1980]. 

Using  weights  to  compensate  for  unequal  observational  error  variances  is 
not  as  straightforward  as  using  zero  weights  to  eliminate  observations  from 
the  analysis.  When  the  variances  of  the  observational  errors,  e^,  are  not 
equal,  the  unweighted  least  squares  estimates  remain  unbiased  but  do  not  have 
minimum  variance.  Minimum  variance  estimates  are  obtained  by  using  weights 
wt^  = 1/Variance [e ^ ] when  the  error  variances  are  known . If  weights  must  be 
estimated,  they  should  be  based  on  at  least  10  degrees  of  freedom  [see  Bement 
and  Williams,  1969].  In  practice,  however,  weights  are  derived  from  theory, 
or  obtained  from  the  data  being  fit,  and  either  of  these  methods  can  do  more 
harm  than  good.  When  the  need  for  weights  is  suspected  and  the  error 
variances  are  not  known,  first  fit  the  data  using  unweighted  least  squares; 
analysis  of  the  residuals  may  confirm  the  need  for  weighting  and  may  also 
provide  estimates  for  the  weights  themselves.  If  the  need  for  weights  is 
confirmed,  then  a statistician  should  be  consulted  to  assist  in  selecting  the 
weights  and  in  interpreting  the  results. 
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Appendix  C 


ESTIMATING  THE  NUMBER  OF  RELIABLE  DIGITS 
IN  THE  RESULTS  OF  A FUNCTION 


The  number  of  reliable  digits,  p,  in  the  results  of  a real  valued 
function,  g(B),  can  be  estimated  in  most  cases  by  evaluating 

p = -log10(  { 1 g( B J ) - [a  + j»b] 1}  ) 

j -—2 , ... , 2 | g ( B ) | 

where 

B 3 is  the  vector  of  the  NPAR  parameters  of  the  function  given  by, 

B^(k)  = B(k)  + B (k)« j « io"(DIG1TS/2)  for  j = _2?  2, 

and  k = 1 , . . . , NPAR, 

where 

DIGITS  is  the  number  of  decimal  digits  carried  by  the  user’s  computer 
for  a single  precision  value  when  the  single  precision  version  of 
STARPAC  is  being  used  and  is  the  number  carried  for  a double  precision 
value  otherwise. 

2 

a = (0.20).  I g(0J). 

j=-2 

2 

b = (0.10).  I j.  g(0J). 

J— 2 

This  procedure  may  underestimate  the  number  of  reliable  digits  if  g(6)  is 
extremely  nonlinear.  A more  elaborate  and  more  robust  procedure  is  described 
in  Gill  et  al.  [1981]. 
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